Shopify AssetLink user guide

The Shopify AssetLink app allows you to link product assets in your Cloudinary Media Library to your Shopify stores, attaching them to products based on metadata matching. This guide walks you through the process, from reviewing existing Shopify links to configuring link settings and running synchronization.

Select assets and choose an AssetLink action

To select assets and choose an AssetLink action:

1. In the Console, use the Product Navigation menu on the left:
   1. Select Assets to navigate to the Assets product.
   2. Select Assets under Media Library to open the Advanced Search.
2. Use the free search text box or the available filters to find the assets you want to sync.
3. Select up to 1000 assets.
   Tip

   To select all visible assets at once, use Command-A (⌘+A on Mac) or Ctrl+A (on Windows/Linux).
4. From the More actions (three dots) menu in the assets toolbar, select the action you want to perform:
   • Link assets to Shopify products opens the product linking workflow.
   • Upload assets to Shopify files opens the Upload to Store Files tab.
   • Create Swatch opens the AI swatch workflow.

     

This opens the Shopify AssetLink dialog box with your selected assets. The selected action determines the tab that opens first. For example, Link assets to Shopify products opens the Link to Products tab.

Tip

To open Shopify AssetLink for a single asset, open the asset's Manage page or Preview pane and click Shopify AssetLink.

Review links to Shopify

The Links to Shopify tab in the asset Preview panel shows where a selected Cloudinary asset is connected in Shopify. Use it to confirm which stores and products already use the asset, adjust its position in product media, or remove it from a product.

To review links for one asset:

1. Select the asset in the Media Library.
2. Open the Shopify AssetLink tab in the Preview panel.
3. Select the Links to Shopify tab.

When you open the tab, AssetLink lists each connected Shopify store reference. For each store, you can:

• Open the connected Shopify file in the store's Content area, or open its references view (where the file is used in themes and elsewhere).
• View products that use the selected asset.
• Open a product directly in Shopify admin (admin.shopify.com).
• See the full product media row, with the selected Cloudinary asset highlighted.

If you opened a Shopify AssetLink workflow with more than one asset selected, use the asset selector in the Links to Shopify tab to choose which asset's Shopify links to review.

Load and refresh linked products

When you first open the tab, AssetLink loads store and product references from the asset's Cloudinary context metadata (shopify_sync). This is fast and doesn't scan your entire Shopify catalog.

Click Refresh to rescan Shopify for products that use the asset and update the link cache on the asset. Use refresh after you change product media outside AssetLink, or when you want to rediscover links on new products.

• Scan limit: Refresh checks up to 5,000 products per store. If your catalog is larger, AssetLink shows a warning when the limit is reached.
• Product search: Before refreshing, you can enter an optional Shopify product search term in the field next to Refresh (for example, a SKU, title fragment, tag, or vendor). AssetLink applies the same search syntax as Shopify admin and scans only matching products—useful on large stores.
• Context metadata: After a successful refresh, AssetLink updates the asset's shopify_sync context with the connected Shopify file and the products found in the scan.

Reorder or remove product media

In each product row, drag the media thumbnails to change their order. To remove the selected asset from a product, hover over its thumbnail and click the remove icon. These changes are saved as a draft until you click the save icon.

The save icon is enabled only when the product row has unsaved changes. Use the revert icon to discard unsaved changes for that product.

When you save a removal and the asset is no longer attached to that product, AssetLink updates the asset's shopify_sync context metadata so that product no longer appears under Links to Shopify the next time you open or reload the tab.

Automate AssetLink workflows

Many AssetLink workflows can also be triggered by automation instead of manually selecting assets in Cloudinary. For example, your team might use MediaFlows, a PIM workflow, a Cloudinary upload workflow, or another backend system to upload new product images to Shopify Files or link product media after assets are approved.

Automation is managed by administrators because it requires AssetLink API keys and store-level configuration. If you need a repeatable automated workflow, ask your administrator to review the AssetLink Developer Guide.

Link assets to Shopify products

The Link to Products tab is the main working area where you organize selected assets and configure how Shopify AssetLink links them to your Shopify products.

Step #1: Open the Link to Products workflow

Follow the Select assets and choose an AssetLink action instructions and select Link assets to Shopify products. The Link to Products tab opens.

Step #2: Select stores to sync to

Select which stores you want to sync to. When you select a store, you can see the number of products matched by the assets in the selection.

Step #3: Configure asset linking

Configure how AssetLink matches your Cloudinary assets to Shopify products and where it places them in product galleries.

Apply transformations before upload

When AssetLink syncs product images to Shopify, it uploads transformed image files rather than the original Cloudinary asset. Your administrator can set a default transformation for all Shopify uploads, and you can override it for the current sync from the Link to Products tab.

Use Apply transformation before upload to choose the default transformation or one of your Cloudinary named transformations. Named transformations appear as t_<name> values and are useful when your team already manages approved renditions in Cloudinary, such as square product crops, marketplace-specific sizes, or padded packshots.

Use Transformation string to review or edit the transformation that will be applied to the selected product images. You can enter a named transformation such as t_shopify_product_square, or a full transformation string such as c_fill,w_1200,h_1200,q_auto. Click away from the field to refresh previews before syncing.

For a full list of all supported transformations and their usage, see the Transformation URL API Reference.

Match assets to products

AssetLink groups your assets and matches them to Shopify products based on the metadata fields you select:

• Cloudinary Field: Choose which Cloudinary metadata field to use for grouping (e.g., SKU, product_id, etc.). AssetLink groups together all assets that share the same value in this field.
• Shopify Field: Select which Shopify field to match against the Cloudinary field. You can match against standard fields like sku, title, tags, or custom metafields.

When a Cloudinary field value matches a Shopify field value, AssetLink links all assets in that group to that product. Here's an example showing assets grouped by product SKU:

Choose how to integrate with existing media

Determine how AssetLink integrates your assets with existing product media. Select one of the following options from the Link Mode dropdown:

• In-Place Overwrite: Updates assets at their current positions in the gallery. If a product has 5 images and you sync 3 matching images, AssetLink replaces the first 3 images while keeping the remaining 2 in place.
• Reset: Removes all existing product media and replaces it with only the assets you're syncing. Use this when you want the synced assets to be the only media for the product.
• Append: Adds the synced assets to the end of the existing media gallery. Existing assets remain unchanged and appear before the newly added assets.
• Prepend: Adds the synced assets to the beginning of the existing media gallery. Existing assets remain unchanged but appear after the newly added assets.
• Specific Position: Inserts the synced assets at a specific position you specify in the gallery, shifting existing assets as needed.

Set asset order

Control the sequence in which your synced assets appear relative to each other within a product's media gallery. You can set the order automatically based on metadata, or manually reorder assets.

Ordering options:

• Order by metadata field: Select a metadata field from Order product assets by... to automatically order assets within each group. For example, if you choose a field like sequence_number or priority, AssetLink arranges the assets based on those values.
• Manual override: Manually reorder assets by dragging and dropping them in one of the viewing modes or using the arrow controls next to each asset. This overrides any automatic ordering.

Step #4: Review and manage assets

In the Link to Products tab below the Link Configuration you can see the assets you selected for sync.

Viewing modes

You can view your assets in two modes:

• Compact Mode: Shows assets in a condensed list format, ideal for quick overview and bulk operations

  

• Regular Mode: Displays assets in a detailed table format with thumbnails, metadata, and individual controls

  

Asset management features

Before syncing, you can make final adjustments to your assets. These features help you fine-tune which assets sync and how they appear:

• Asset Exclusion: Click on an asset thumbnail to exclude it from the sync, or click the (-) button next to a group to exclude the entire group
• Manual Reordering: Drag and drop assets to reorder them within groups
• Alt Text Management: Set custom alt text for each asset or use AI-generated alt text where available. Your administrator can also configure whether default alt text comes from Cloudinary (for example, display name, contextual alt, or structured metadata) or from the matched Shopify product (for example, title or handle). See Alt Text Source in the Admin guide.
• Asset Type Detection: AssetLink automatically detects and handles different asset types. Product images sync to the product media gallery, while swatches sync to Shopify files and the cloudinary.swatch metafield (swatches don't appear in the ordered product gallery).

Step #5: Sync and monitor progress

After you configure your link settings and asset order, you can sync your assets to Shopify.

To start the sync:

1. Review your asset groups and configuration.
2. From the Link Configuration section, click the Link X assets in Y groups to Z products button to begin syncing assets to the selected Shopify stores.
   Tip

   Before you actually perform the sync, click Dry run to preview what the results will be.

AssetLink provides several features to help you monitor and manage the sync process:

• Progress Tracking: View real-time progress updates during sync operations
• Error Handling: Review detailed error reporting for any failed operations
• Abort Capability: Cancel sync operations in progress if needed
• Sync Reports: Download detailed reports of sync operations for your records

Upload assets to Shopify files

The Upload to Store Files tab allows you to upload assets directly to your Shopify store's file library without linking them to specific products. This is useful for general assets like logos, banners, or other store-wide content that isn't associated with specific products.

The upload workflow also supports transformation overrides. Use Upload Transformation to select the default transformation or a Cloudinary named transformation, and use Transformation string to type or edit the exact transformation that should be applied before the asset is uploaded to Shopify Files.

To upload assets to Shopify:

1. Follow the Select assets and choose an AssetLink action instructions and select Upload assets to Shopify files. The Upload to Store Files tab opens.
2. Optional: Select or edit the upload transformation for this batch.
3. Click Upload to Shopify Files to upload the selected Cloudinary assets to Shopify.

Use this option when products don't exist yet, or when you're uploading site-wide images and videos that don't belong to any particular product.

Generate AI swatches

The AI Swatch tab helps generate color or fabric swatch assets from selected product images. To open it from the asset toolbar, select Create Swatch. When more than one asset is selected, choose the asset you want to work with from the asset selector in the tab.

To generate and save a swatch:

1. Select the source asset from the asset selector.
2. In Product Type Field, choose the value that best describes the product in the image, such as shirt, pants, handbag, or accessory. This value helps the AI focus on the right object when the image contains a model, background, or multiple materials.
3. Click Generate Swatch. AssetLink sends the selected image to the configured AI image provider, which generates a square fabric or color sample. The result is shown as a preview — nothing is saved to Cloudinary yet.
4. Review the generated swatch. If you prefer to create the swatch yourself, click Manual Crop and select a square area from the product image.
5. Choose the Name Source for the swatch. You can use manual entry or an available field from the source asset.
6. Optional: Select Normalize filename to lowercase the generated filename and replace unsupported characters with underscores.
7. Click Save to Cloudinary.

When you save, Shopify AssetLink uploads the generated swatch as a new image asset in Cloudinary. The generated image is saved separately from the source product image; the source image isn't overwritten. If your administrator configured an Asset Type Metadata Field, the uploaded swatch is automatically marked with the value swatch. This lets later product syncs treat the asset as a swatch instead of adding it to the normal product media gallery.