Shopify AssetLink developer guide

The Shopify AssetLink developer guide covers the HTTP APIs and Shopify theme integrations used to automate asset syncing and enable optimized Cloudinary delivery.

Use this guide when you want to trigger AssetLink from upload webhooks, MediaFlows flows, CI jobs, PIM or DAM workflows, or other backend automation systems, or when you want to configure Cloudinary delivery in your Shopify theme.

AssetLink API

Shopify AssetLink exposes an HTTP API that automation systems can use to upload Cloudinary assets to Shopify files, link assets to Shopify products, manage existing links, and generate AI swatches.

For complete API documentation, see the AssetLink API reference:

https://assetlink.cloudinary.app/api/docs

Generate an API key

AssetLink API keys are scoped to a Shopify store connection. Create a separate key for each automation owner or system so you can revoke access without affecting other integrations.

To create an API key from Shopify admin:

1. In Shopify admin, go to Apps.
2. Open Cloudinary AssetLink.
3. Go to Settings.
4. Select API Keys.
5. Enter a descriptive label, such as MediaFlows production sync.
6. Click Generate API Key.
7. Copy the key immediately and store it in your automation platform's secret manager. The key is shown only once.

You can also create and manage keys from Shopify AssetLink in Cloudinary:

1. In the Console, make sure Assets is selected.
2. Select App Marketplace.
3. Find Shopify AssetLink.
4. Click Settings to open the Setup tab.
5. Make sure a Shopify store is connected.
6. Generate keys in the API keys section.

Authenticate requests

Send the API key in the Authorization header:

Most API calls also include the Cloudinary cloudName, the target Shopify stores, and the Cloudinary asset data to process. For example, an automation can call POST /api/cloudinary/sync/files after a Cloudinary upload to push the new asset into one or more Shopify stores. Set shopifyFilenameUsage to use_display_name to upload files using the asset display name, or use_public_id to use the Cloudinary public ID.

See the AssetLink API reference for request schemas, examples, and streaming response details.

Validate API connectivity

Send a GET request to /api/assetlink/ping with your API key:

A successful response returns ok: true plus the connected shop domain and cloudName. Use this from MediaFlows, deployment checks, or monitoring before running heavier sync calls.

Link products with thin asset references

For POST /api/cloudinary/sync/products, callers can send thin asset entries with only:

• publicId (required)
• resourceType (optional, default image)
• deliveryType (optional, default upload)

AssetLink hydrates full asset metadata from Cloudinary using cloudinaryApiKey and cloudinaryApiSecret in the request body. This is the recommended shape for upload webhooks, MediaFlows, and other automations that know an asset's public_id but don't already hold the full Cloudinary resource object.

You still send mapping, storeId, cloudName, and the usual link options (linkMode, orderingMode, defaultImageTransformation, and so on). See the API reference for examples.

Override alt text in product sync API calls

The optional request field selectedAltTextField on POST /api/cloudinary/sync/products overrides the store default Alt Text Source for that call. Use the same values as in setup (for example, Shopify:title, Cloudinary:display_name, or Cloudinary:metadata.<field_external_id>).

Set variant images in product sync API calls

When you sync products through POST /api/cloudinary/sync/products, AssetLink can also set Shopify variant images from your Cloudinary assets. AssetLink matches each image to variants either by SKU or by option values, such as color and size. See the API reference for the request fields.

Manage existing Shopify links for a DAM asset

Use POST /api/dam-asset-links when automation needs to review or update the Shopify products already linked to one Cloudinary asset. For example, a MediaFlows flow can remove an asset from a Shopify product after approval status changes, or refresh the cached link list after another workflow updates Shopify media.

This endpoint supports these intents:

• load: Loads cached Shopify link data from Cloudinary context metadata and verifies that each cached product still references the asset.
• refresh: Scans Shopify for products that reference the asset, then replaces the asset's cached shopify_sync product list. The response streams newline-delimited JSON.
• save_order: Reorders the asset's product media for one Shopify product and updates the productmedia_v1 metafield.
• remove: Removes selected Shopify media references from one product, updates media order and productmedia_v1, and removes the product from the asset's shopify_sync context when it is no longer linked.
• remove_from_all_products: Removes the asset from every product currently listed in the asset's shopify_sync context metadata across connected stores. It doesn't scan Shopify for additional products.
• update_position_on_all_products: Moves the asset to a new 1-based gallery position on every product currently listed in the asset's shopify_sync context metadata. It doesn't scan Shopify for additional products.

Authentication for dam-asset-links

The request must include cloudName and one of the supported authentication methods:

• AssetLink API key: Send Authorization: Bearer <assetlink_api_key>. cloudName selects and validates the Cloudinary account associated with the key; every requested Shopify store must be connected to that account.
• Cloudinary DAM session token: Used by the embedded AssetLink app in Cloudinary.

Cloudinary API key and secret values aren't accepted as Bearer-token authentication for Shopify store operations. For intents that need to read or update Cloudinary context metadata, include cloudinaryApiKey and cloudinaryApiSecret in the JSON body after authenticating with an AssetLink API key or DAM session token.

Minimum request fields by intent

Example removal request

Shopify Flow

AssetLink integrates with Shopify Flow, so you can automate asset workflows in Shopify without calling the AssetLink API directly.

Trigger:

• Cloudinary asset changed: Starts a workflow when a Cloudinary asset is uploaded, retagged, moved, renamed, or deleted, or when its metadata changes.

Actions:

• Link assets: Link Cloudinary assets to product galleries, variant images, collection images, blog post images, file metafields, and Shopify files, using matching rules you set up in AssetLink.
• Remove links: Remove the links AssetLink created for an asset, for example, when the asset is deleted in Cloudinary.
• Find assets: Find Cloudinary assets by folder, by search expression, or by visual similarity to an image.
• Upload and save: Upload images to Cloudinary, and save Cloudinary assets to Shopify files.

To control which changes reach Shopify Flow, choose which Cloudinary product environments send their asset changes to Shopify Flow in the AssetLink settings.

Shopify theme setup for optimized delivery

To deliver assets through Cloudinary's global CDN in your Shopify storefront, you need theme-level changes in addition to the AssetLink app setup. This is separate from syncing assets to Shopify products. It controls how images and videos are delivered to shoppers.

You can use the Cloudinary Shopify theme delivery sample and Liquid snippets as a reference implementation for adding Cloudinary delivery URLs to your Shopify theme.

For assistance with setting up optimized delivery, contact Cloudinary support.