> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/digital-asset-management-dam/plugins-and-connectors/connectors/shopify-connector.md). # Shopify Connector ## Shopify Connector — Setup & Usage Guide ### Table of Contents 1. Overview 2. Prerequisites 3. Creating a Shopify Connector 4. Onboarding Wizard * Step 1 — Connect to Shopify (OAuth) * Step 2 — Configure DAM API Key * Step 3 — Field Mappings * Step 4 — Webhook Setup 5. Dashboard 6. Settings 7. Webhook Management 8. Sync Operations * DAM → Shopify (Automatic) * Shopify → DAM (Automatic) 9. Metafield Sync 10. Webhook Logs & Monitoring 11. Troubleshooting *** ### 1. Overview The **Shopify Connector** enables bidirectional synchronization between your Scaleflex DAM and your Shopify store: * **DAM → Shopify:** When you upload or update an asset in your DAM, it is automatically pushed to the correct Shopify product's media gallery (or metafield). * **Shopify → DAM:** When product images are added or updated in Shopify, they are automatically pulled into your DAM and organized by product SKU. The connector works through Shopify webhooks and DAM webhooks, so syncs happen in near real-time without any manual intervention. *** ### 2. Prerequisites Before setting up the Shopify Connector, make sure you have: | Requirement | Details | | ------------------------- | ------------------------------------------------------------------------------------------ | | **Shopify store** | Admin access to a Shopify store (any plan) | | **Shopify Custom App** | A custom app created in your Shopify Partners or Shopify Admin with the correct API scopes | | **Required OAuth scopes** | `write_products`, `read_products` , `write_files`, `read_files` | | **Scaleflex DAM account** | A DAM account with a Hub API Key | | **DAM metadata fields** | At least one text field configured in your DAM to hold the product SKU | #### Creating a Shopify Custom App If you do not already have a Shopify Custom App, follow these steps: 1. In your Shopify Admin, go to **Settings → Apps and sales channels → Develop apps -> Build apps in Dev Dashboard**. 2. Click **Create app** and give it a name (e.g., "Scaleflex DAM Connector"). For the **App URL,** it's not required, so you can fill in something like: ****
3. Add the scopes following: * `write_products` * `read_products` * `write_files` * `read_files` 4. Add the following URL as a **Redirect URLs** (We will provide this URL when setting up the connector in the Hub):
``` https://{your-integration-domain}/{lang}/{token}/shopify/oauth/callback ``` 5. Install the app on your store and copy the **Client ID** and **Client Secret** in the Settings. *** ### 3. Creating a Shopify Connector 1. Log in to the Scaleflex DAM -> Settings -> Automations -> Integration platform. 2. Navigate to **Connectors** and click **Add Connector**. 3. Select **Shopify** as the connector type. 4. Fill in the following fields: | Field | Description | | ------------------------ | -------------------------------------------------------------------- | | **Connector Name** | A friendly name for this connector (e.g., "My Shopify Store") | | **Shopify Store Domain** | Your store's `.myshopify.com` domain (e.g., `example.myshopify.com`) | | **Client ID** | The API key from your Shopify Custom App | | **Client Secret** | The API secret key from your Shopify Custom App | To find the **Shopify Store Domain**, go to **Settings** in the **Admin Dashboard**. Example: **demo.myshopify.com**
5. Click **Save**. The connector is created, and the onboarding wizard opens automatically. *** ### 4. Onboarding Wizard The onboarding wizard guides you through all the required setup steps. You must complete all steps before the connector becomes active. #### Step 1 — Connect to Shopify (OAuth) This step authorizes the integration to access your Shopify store. 1. Click **Connect to Shopify**. 2. You are redirected to the Shopify OAuth authorization page. 3. Review the requested permissions and click **Install app**. 4. You are redirected back to the onboarding wizard with a success confirmation. > **Note:** If you see an error on redirect, verify that the **Allowed redirection URL** in your Shopify app settings matches exactly the URL shown in the connector. After a successful connection, the connector stores your access token securely. It also automatically registers an `APP_UNINSTALLED` webhook so the connector is notified if the app is removed from your Shopify store. *** #### Step 2 — Configure DAM API Key This step connects the integration to your Scaleflex DAM account. 1. Enter your **DAM HUB API Key.** 2. Click **Test Connection** to verify the key is valid. 3. If the test succeeds, click **Next**. > **Where to find your HUB API Key:** Log in to your Scaleflex DAM, go to **Settings → Access → API Keys**. *** #### Step 3 — Field Mappings This is the most important configuration step. You define which DAM metadata fields carry the information needed to sync assets with Shopify. **Product SKU Field (required)** The **Product SKU Field** is a metadata field in your DAM. When an asset has a value in this field, the connector uses that value to find the matching Shopify product by SKU and sync the asset to it. * Select the DAM field that contains the **Shopify product SKU**. * Example: if your DAM field is named `product_sku` and an asset has `product_sku = "SHIRT-001"`, the connector will find the Shopify product with that SKU and add the asset to its media gallery. **Variant SKU Field (optional)** The **Variant SKU Field** lets you pin a specific media item to one or more product variants rather than the whole product. * Select the DAM field that contains the **variant SKU**. * The field value format: `VARIANT-SKU` or `VARIANT-SKU:position` (for ordering). * Example: `"RED-SHIRT-SM:0,RED-SHIRT-MD:1"` pins the asset as the first image for size Small and the second image for size Medium. **Preset Field (optional)** The **Preset Field** tells the connector which image transformation preset to apply before pushing to Shopify. * Select the DAM field that holds the **preset name**. * If an asset does not have a preset value, the connector pushes the original CDN URL. **Metafield Configuration (optional)** If you want to sync DAM assets to **Shopify product metafields** (instead of, or in addition to, the media gallery): 1. Enable the **Metafield Sync** toggle. 2. Select the **Metafield Target Field** — a DAM metadata field whose value specifies which Shopify metafield to populate. 3. Click **Load Metafields** to fetch the list of metafield definitions from your Shopify store. 4. Select the metafields you want to support from the list. 5. Click **Sync Metafields to DAM** — this populates the selected DAM field's dropdown options with the available metafield identifiers. **How it works:** When an asset in the DAM has the Metafield Target Field set to, for example, `pd_custom_product_image`, the connector sets that asset as the value of the `custom.product_image` metafield on the Shopify product. *** #### Step 4 — Webhook Setup This step shows you the **incoming webhook URL** that the DAM will use to notify the connector when an asset changes. The webhook URL is pre-configured and contains embedded credentials. You do not need to set anything up manually here — just copy the URL and configure it in your DAM: 1. Copy the **Webhook URL** displayed on screen. 2. In your Scaleflex DAM, go to **Settings → Automations → Webhooks**. 3. Create a new webhook subscription pointing to this URL. 4. Paste the copied URL into the **Hostname** field, then **Webhook URL** will be generated. 5. Select the events: **"On upload"** and **"On change metadata"**.
5. Select **"Data to send"** the same as the picture example. 6. Save the webhook in your DAM. > **Security note:** The webhook URL contains a unique hash. Keep this URL confidential — treat it like a password. After completing this step, click **Finish Setup** to complete the onboarding. *** ### 5. Dashboard After completing onboarding, you land on the **Dashboard**, which shows a real-time overview of your connector's activity. #### Summary Cards | Card | Description | | --------------------- | --------------------------------------------------- | | **Assets Synced** | Total number of asset sync operations recorded | | **Failed** | Number of sync attempts that ended in an error | | **Conflicts** | Assets where sync was skipped due to a conflict | | **Success Rate** | Percentage of successful syncs | | **Webhooks Received** | Total DAM webhook events received by this connector | #### Recent Activity A live list of the last 10 webhook events, showing the file, trigger type, status, and time. Click any row to view the full execution trace. #### Sync Breakdowns Charts showing distribution by: * **Direction** — DAM→Shopify vs. Shopify→DAM * **Target type** — Media gallery vs. Metafield * **Media type** — Image, Video, 3D Model, etc. > **Note:** If the app was uninstalled from your Shopify store, a warning banner appears at the top of the dashboard. Use the **Reconnect** button to re-authorize via OAuth. *** ### 6. Settings Go to **Settings** to adjust the connector configuration after onboarding. #### General Tab | Setting | Description | | ------------------------ | ------------------------------------------------- | | **Connector Name** | Display name for this connector | | **DAM HUB API Key** | Update the DAM API key (with Test button) | | **Reconnect to Shopify** | Re-run the OAuth flow to refresh the access token | #### Field Mappings Tab Update any of the field mappings configured during onboarding: * Product SKU Field * Variant SKU Field * Preset Field * Metafield Target Field + metafield selection #### Folder Structure Tab Controls how uploaded Shopify assets are organized inside your DAM. | Setting | Options | Description | | --------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DAM Upload Folder** | Any folder path | The root folder where Shopify→DAM assets are stored (e.g., `/shopify/products`) | | **Folder Structure** | `Flat` | **Flat**: all files in one folder | | **On Update Policy** | `Keep` / `Replace` / `Replace & Delete` | Controls what happens when a DAM asset is updated and pushed to Shopify again: **Keep** = skip if media already exists; **Replace** = upload new version and remove old media; **Replace & Delete** = replace and delete the old Shopify file from the store's file library | #### Webhooks Tab Manage the Shopify webhook subscriptions that trigger Shopify→DAM sync. | Webhook Topic | Purpose | | ----------------- | --------------------------------------------------------------------- | | `PRODUCTS_CREATE` | Triggered when a new product is created in Shopify | | `PRODUCTS_UPDATE` | Triggered when a product (including its images) is updated in Shopify | For each topic, click **Install** to register the webhook or **Uninstall** to remove it. > **Recommendation:** Install both `PRODUCTS_CREATE` and `PRODUCTS_UPDATE` to ensure all product image changes are automatically synced to your DAM. *** ### 7. Webhook Management #### Installing Webhooks Webhooks must be installed individually per topic. The connector registers these webhooks directly with Shopify using your access token. 1. Go to **Settings → Webhooks**. 2. For each topic, click **Install**. 3. A green badge confirms the webhook is active. The display shows the webhook ID and creation date. #### What Happens if a Webhook Fires When Shopify sends a webhook, the connector: 1. Verifies the HMAC signature using your Client Secret (rejects invalid requests). 2. Creates a log entry with the full payload. 3. Dispatches an async background job to process the sync. 4. Updates the log with the outcome (Success, Partial, or Failed). #### App Uninstalled Webhook An `APP_UNINSTALLED` webhook is automatically registered when you complete onboarding. If the Shopify app is uninstalled, the connector marks itself as disconnected and shows a banner on the Dashboard. The connector stops processing webhooks until reconnected via OAuth. *** ### 8. Sync Operations #### 8.1 DAM → Shopify (Automatic) This sync is triggered automatically when a file is **uploaded** or **metadata is changed** in your DAM. **How it works:** 1. A file in your DAM has a value in the **Product SKU Field** (e.g., `product_sku = "SHIRT-001"`). 2. You upload the file or change its metadata. 3. The DAM sends a webhook to the connector's incoming URL. 4. The connector: * Reads the product SKU from the asset's metadata. * Finds the matching Shopify product by SKU. * Applies the configured preset to the CDN URL (if any). * Uploads the asset to the product's media gallery. * Records the result in the webhook log. **Multiple SKUs:** An asset can be synced to multiple products. Set the Product SKU Field to a comma-separated list (e.g., `SHIRT-001, SHIRT-002`). **Variant pinning:** Set the Variant SKU Field to pin the asset to a specific variant within the product (e.g., `RED-SHIRT-SM:0`). The number after the colon sets the display position. **Update behavior:** Controlled by the **On Update Policy** in Settings: * `Keep` — If the product already has a media item from this asset, skip the re-upload. * `Replace` — Remove the old media item and upload the new version. * `Replace & Delete` — Same as Replace, but also delete the old file from Shopify's file library. *** #### 8.2 Shopify → DAM (Automatic) This sync is triggered automatically when a product's images are added or changed in Shopify. **How it works:** 1. A product is created or updated in Shopify (with images). 2. Shopify sends a `PRODUCTS_CREATE` or `PRODUCTS_UPDATE` webhook to the connector. 3. The connector: * Reads all media items from the product payload. * Skips images that were originally pushed from the DAM (avoids duplication). * Uploads new images to the DAM (in the configured folder + folder structure). * Tags each asset with the product's SKU metadata. * Records each asset in the mapping table. **Deduplication:** The connector tracks each image by its Shopify image ID. If an image has already been synced, it is skipped on subsequent updates. **Loop prevention:** The connector uses a short-lived lock to prevent a DAM→Shopify sync from triggering a Shopify→DAM sync in response (and vice versa). *** ### 9. Metafield Sync Metafields allow you to store structured data on Shopify products beyond the default fields. The Shopify Connector can sync DAM assets directly into metafields. #### Supported Metafield Types | Shopify Type | Behavior | | ------------------------ | ------------------------------------------------------------------------------------------- | | `file_reference` | The asset is uploaded to Shopify's file library and the file GID is stored in the metafield | | `single_line_text_field` | The asset's CDN URL (with preset applied) is stored as text | #### How to Use Metafields 1. During onboarding (or in **Settings → Field Mappings**), enable metafield sync and select the metafields you want to support. 2. In your DAM, set the **Metafield Target Field** on the asset to the metafield identifier (e.g., `pd_custom_product_image` for a product-level metafield, or `pv_custom_variant_image` for a variant-level metafield). 3. When the asset is uploaded or updated, the connector automatically sets the metafield value on the correct Shopify product or variant. **Metafield identifier format:** * `pd_{namespace}_{key}` — Product-level metafield (e.g., `pd_custom_product_image`) * `pv_{namespace}_{key}` — Variant-level metafield (e.g., `pv_custom_variant_image`) #### Metafield Sync Logs Go to **Settings → Metafield Logs** to see the history of metafield definition syncs (the job that populates the DAM field's dropdown options from your Shopify store's metafield definitions). *** ### 10. Webhook Logs & Monitoring Go to **Logs** in the navigation to view the full history of sync activity. #### Tabs | Tab | Shows | | ------------------ | ---------------------------------------------------------- | | **Sync Logs** | All DAM→Shopify sync events (one row per webhook received) | | **Shopify→DAM** | All Shopify→DAM image import logs | | **Asset Mappings** | All tracked DAM↔Shopify asset relationships | #### Sync Logs — Filters You can filter by: * **Status** — Success, Partial, Failed, Pending, Processing * **Search** — Filter by file UUID or product SKU * **Date range** — Show logs from a specific time window * **Auto-refresh** — Enable live refresh to monitor in-progress syncs #### Log Detail View Click any log row to open the detail view, which shows: * **Metadata:** file UUID, trigger type (FILE\_UPLOAD / FILE\_CHG\_META), status, timestamps * **Payload:** the raw webhook payload received from the DAM * **Sync Results:** which SKUs were synced, which failed, which preset was used, the final CDN URL * **Step Trace:** a step-by-step breakdown of the job execution (expand individual steps to see input/output data and timing) #### Retrying Failed Syncs If a sync failed (and it has not exceeded the retry limit), a **Retry** button appears on the detail page. Clicking it re-dispatches the sync job with the original webhook payload. *** ### 11. Troubleshooting #### OAuth Connection Failed **Symptom:** Redirect back from Shopify shows an error or redirects to an unexpected page. **Checks:** * Verify the **Allowed redirection URL** in your Shopify app settings exactly matches the callback URL shown in the connector. * Ensure the **Client ID** and **Client Secret** were entered correctly during connector creation. * The OAuth state token is single-use. If the browser went back and retried, re-initiate the OAuth flow from the connector settings. *** #### Assets Not Syncing to Shopify **Symptom:** You upload a file to the DAM but nothing appears in Shopify. **Checks:** 1. Verify the DAM asset has a value in the **Product SKU Field**. 2. Confirm a product with that exact SKU exists in Shopify. 3. Check that the DAM webhook (configured in Step 4 of onboarding) is active and pointing to the correct URL. 4. Go to **Logs** and check if a webhook log entry was created. If yes, expand the step trace to find the error. 5. Verify the connector's access token is still valid — go to Settings and click **Reconnect to Shopify** if needed. *** #### Shopify Images Not Appearing in DAM **Symptom:** You add images to a Shopify product but they do not appear in the DAM. **Checks:** 1. Go to **Settings → Webhooks** and confirm that `PRODUCTS_UPDATE` is installed (green status badge). 2. Go to **Logs → Shopify→DAM** and check if a sync log entry was created after the product change. 3. If the image was originally pushed from the DAM (DAM→Shopify), it is intentionally skipped to avoid duplication. *** #### App Uninstalled Banner **Symptom:** Dashboard shows "App Uninstalled" warning. **Resolution:** 1. Reinstall the Shopify Custom App in your Shopify Admin. 2. Return to the connector dashboard and click **Reconnect**. 3. Complete the OAuth flow. The connector resumes processing once reconnected. *** #### Metafields Not Appearing as Options **Symptom:** The Metafield Target Field in the DAM does not show the expected metafield options. **Resolution:** 1. Go to **Settings → Field Mappings**. 2. Click **Load Metafields** to refresh the list from Shopify. 3. Ensure the desired metafields are selected and click **Sync Metafields to DAM**. 4. Wait a few seconds and check **Settings → Metafield Logs** to confirm the sync completed successfully. *** #### Rate Limiting **Symptom:** Sync logs show errors mentioning "rate limit" or "429". The connector automatically retries Shopify API calls up to 3 times with backoff when rate-limited. If you see persistent rate limit errors, this usually indicates very high concurrent sync volume. The connector will process the backlog automatically — no manual action is required. *** *For additional support, contact your Scaleflex account manager or visit the support portal.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.scaleflex.com/digital-asset-management-dam/plugins-and-connectors/connectors/shopify-connector.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.