> ## Documentation Index
> This page relates to Cloudinary Integrations. Fetch the complete documentation index for all Cloudinary Integrations at: https://cloudinary.com/documentation/llms-integrations.txt?referrer=docpage and then use it to discover all relevant pages before exploring further.
> If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage

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

> **NOTE**: Treat AssetLink API keys as secrets. Don't put them in browser code, Liquid templates, public repositories, or client-side workflow steps. If a key is exposed, revoke it and generate a replacement.

### Authenticate requests

Send the API key in the `Authorization` header:

```bash
Authorization: Bearer <assetlink_api_key>
```

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](https://assetlink.cloudinary.app/api/docs) for request schemas, examples, and streaming response details.

### Validate API connectivity

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

```bash
curl -s https://assetlink.cloudinary.app/api/assetlink/ping \
  -H "Authorization: Bearer <assetlink_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](https://assetlink.cloudinary.app/api/docs) 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>`).

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

| Intent | Minimum fields |
| --- | --- |
| `load` | `cloudName`, `intent`, `publicId`, `links[]` with `storeId` and `fileGid` |
| `refresh` | `cloudName`, `intent`, `publicId`, `assetId`, `links[]` with `storeId` and `fileGid` |
| `save_order` | `cloudName`, `intent`, `storeId`, `productId`, `publicId`, `fileGid`, `mediaOrder[]` |
| `remove` | `cloudName`, `intent`, `storeId`, `productId`, `publicId`, `fileGid`, and either `mediaIds[]`/`mediaId` or `publicIds[]` |
| `remove_from_all_products` | `cloudName`, `intent`, and either `assetId` or `publicId` + `resourceType` + `deliveryType`. External callers authenticate with an AssetLink API key and include `cloudinaryApiKey` and `cloudinaryApiSecret` for Cloudinary context access. |
| `update_position_on_all_products` | `cloudName`, `intent`, `newPosition`, and either `assetId` or `publicId` + `resourceType` + `deliveryType`. External callers authenticate with an AssetLink API key and include `cloudinaryApiKey` and `cloudinaryApiSecret` for Cloudinary context access. |

#### Example removal request

```bash
curl https://assetlink.cloudinary.app/api/dam-asset-links \
  -H "Authorization: Bearer <assetlink_api_key>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "cloudName": "my-cloud",
    "intent": "remove",
    "storeId": "my-store.myshopify.com",
    "productId": "gid://shopify/Product/10356234223903",
    "publicId": "Products/1798400504235_1",
    "fileGid": "gid://shopify/MediaImage/56727991025951",
    "mediaIds": ["gid://shopify/MediaImage/56727991025951"],
    "mediaOrder": ["gid://shopify/MediaImage/55730874351903"],
    "assetId": "e6606c520c4683f7ae2ff08585fb631d",
    "resourceType": "image",
    "deliveryType": "upload"
  }'
```

> **NOTE**: All Shopify Admin API calls are made by AssetLink on the server. Don't send Shopify Admin access tokens from browser code, MediaFlows, or other external callers.

## 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](https://github.com/cld-et/cloudinary-shopify-theme-delivery) as a reference implementation for adding Cloudinary delivery URLs to your Shopify theme.

For assistance with setting up optimized delivery, [contact Cloudinary support](https://support.cloudinary.com/hc/en-us/requests/new).