Ctrlk
Help CenterRelease NotesBlogWebsite
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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").

  1. Add the scopes following:

    • write_products

    • read_products

    • write_files

    • read_files

  2. Add the following URL as a Redirect URLs (We will provide this URL when setting up the connector in the Hub):

  1. 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

  1. 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 (starts with sk_live_...).

  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. Select the events: "On upload" and "On change metadata".

  1. Select "Data to send" the same as the picture example.

  2. 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.

PreviousZapier automationNextMCP Server

Last updated