> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 selecting assets to configuring the sync settings and running the synchronization.
> **NOTE**: Shopify AssetLink is available on the free tier of Cloudinary for Shopify Core customers. For Shopify Plus customers, a Cloudinary Enterprise or Pro+ plan is required to use AssetLink after a 30-day trial. 

Don't have a Cloudinary account yet? [Sign up for free](https://cloudinary.com/users/register_free). If you are a Shopify Plus customer, please [contact us](https://cloudinary.com/contact) for pricing and setup options.

> **INFO**: Make sure your administrator has installed and configured the app both on Shopify and in Cloudinary. For instructions, see the Shopify AssetLink [Admin Guide](shopify_assetlink_admin_guide).

## Select assets and open AssetLink

**To select assets and open AssetLink:**

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 (3-dots) option menu in the assets toolbar, select **Shopify AssetLink**.![Shopify AssetLink option for selected assets](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_select_assets.png "thumb: w_700,dpr_2, width: 700, popup:true")

This opens the **AssetLink app in Cloudinary Assets** dialog box with your selected assets. The **Link to Products** tab opens by default for non-admins.

![Link to Products tab showing store selection and sync configuration options](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_product_tab.png "thumb: w_700,dpr_2, width: 700, popup:true")

> **INFO**:
>
> For users with admin roles (Media Library Admin, Master Admin, or Technical Admin), the **Setup** tab opens by default instead. All users can view the **Setup** tab to review configuration settings, but only admins can make changes. For configuration details, see [Setup and configuration](shopify_assetlink_admin_guide#setup_and_configuration) in the Admin guide.

## Link assets to Shopify products

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

### Step #1: Open AssetLink

Follow the [Select assets and open AssetLink](#select_assets_and_open_assetlink) instructions, then ensure you're on the **Link to Products** tab. 

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

![Sync to stores](https://cloudinary-res.cloudinary.com/image/upload/c_crop,w_550,h_320,g_north_west,y_300,x_50/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_product_tab.png "thumb: w_300,dpr_2, width: 300, popup:true")

### Step #3: Configure asset linking

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

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

![Match by field configuration](https://cloudinary-res.cloudinary.com/image/upload/c_crop,w_1150,h_250,g_north,y_300,x_300/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_product_tab.png "thumb: w_400,dpr_2, width: 400, popup:true")

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:

![Assets grouped by SKU](https://cloudinary-res.cloudinary.com/image/upload/c_crop,g_south,h_120,w_1750,y_30/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_compact_view.png "thumb: w_700,dpr_2, width: 700, popup:true")

#### 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:

![Link mode](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_link_mode.png "thumb: w_300,dpr_2, width: 300, popup:true")

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

> **NOTE**:
>
> If you want to overwrite some existing assets while also adding new ones, you'll need to run the sync operation twice: once with **In-Place Overwrite** mode to replace existing assets, and then again with **Append**, **Prepend**, or **Specific Position** mode to add the new assets.

#### 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.![Ordering options](https://cloudinary-res.cloudinary.com/image/upload/c_crop,w_380,h_150,g_north,y_530,x_380/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_product_tab.png "thumb: w_300,dpr_2, width: 300, popup:true")
* **Manual override**: Manually reorder assets by dragging and dropping them in one of the [viewing modes](#viewing_modes) or using the arrow controls next to each asset. This overrides any automatic ordering.

> **NOTES**: If you change the ordering metadata field after manually reordering assets, AssetLink warns you that your manual changes will be lost.

### 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![Selected assets grouped by SKU shown in Compact view](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_compact_view.png "thumb: w_700,dpr_2, width: 700, popup:true")
* **Regular Mode**: Displays assets in a detailed table format with thumbnails, metadata, and individual controls![Selected assets grouped by SKU shown in Non-Compact view](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_non_compact_view.png "thumb: w_700,dpr_2, width: 700, popup:true")

#### 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
* **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.![Selected assets grouped by SKU shown in Non-Compact view](https://cloudinary-res.cloudinary.com/image/upload/c_crop,w_500,h_70,g_north,y_800,x_5/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_product_tab.png "thumb: w_300,dpr_2, width: 300, popup:true")
   > **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

> **TIP**:
>
> If you want to apply specific transformations to the images you're syncing, ask your administrator to change the **Default image transformation** setting for a specific batch. For more information, see [Default image transformation](shopify_assetlink_admin_guide#default_image_transformation) in the Admin Guide.

## Upload assets to store 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.

**To upload assets to Shopify:**

1. Follow the [Select assets and open AssetLink](#select_assets_and_open_assetlink) instructions, then switch to the **Upload to Store Files** tab.
2. Click **Upload to Shopify Files** to upload the selected Cloudinary assets to Shopify.

![AssetLink app opened Upload to Store File tab selected](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/docs/integrations/assetlink_upload_to_store_file_tab.png "thumb: w_700,dpr_2, width: 700, popup:true")

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.

> **TIP**:
>
> If you want to apply specific transformations to the assets you're uploading, ask your administrator to change the **Default transformation** setting for a specific batch. For more information, see [Default transformation](shopify_assetlink_admin_guide#default_transformation) in the Admin Guide.