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

# Cloudinary Image and Video for Shopify


This guide shows you how to set up Cloudinary's image and video optimization, transformations, and delivery for your Shopify store using theme-level changes. This approach keeps Shopify as the origin for your media files, while Cloudinary acts as a caching proxy that optimizes, transforms, and delivers them. You can typically complete this implementation in one day and boost site performance by up to 30%.

> **NOTES**: For full Digital Asset Management (DAM) capabilities, including centralized asset management and metadata-based syncing to Shopify, see the [Shopify AssetLink app](shopify_assetlink_dam_delivery).

## Prerequisites

* A Cloudinary account with access to the Assets product. If you don't yet have a Cloudinary account, you can [sign up for free](https://cloudinary.com/users/register_free).
* At least one Shopify store where you want to sync assets

## Overview

In order to set up your Shopify-Cloudinary integration, you'll need to do the following:

1. [Set up your Cloudinary account to allow delivery of the Shopify store's images and videos](#stage_1_cloudinary_account_setup)
2. [Edit your store theme code to use Cloudinary image URLs instead of Shopify image URLs](#stage_2_shopify_theme_setup)

## Stage 1: Cloudinary account setup

### Set up upload mapping

Upload mappings allow Cloudinary to fetch and deliver assets from your Shopify store. An upload mapping maps a Cloudinary folder to an external URL, enabling Cloudinary to act as a caching proxy for your Shopify media.

**To set up an upload mapping:**

1. Go to the [Auto Upload Mapping](https://console.cloudinary.com/app/settings/upload/mapping) tab of the Upload page in Console Settings.
2. Click **Add Mapping**.
3. Configure the mapping fields with the following values:

| Field | Value |
|-------|-------|
| **Source URL prefix** | `https://store-name.myshopify.com/cdn/shop/` |
| **Target folder** | `shop` |

Replace `store-name` with your actual Shopify store ID.

![Upload mapping configuration](https://cloudinary-res.cloudinary.com/image/upload/v1770109297/docs/integrations/shopify_upload_mapping.png "thumb: w_500,dpr_2, width: 500, popup:true")

> **INFO**: You can't reuse the target folder name for other stores. In this setup, we recommend using one Cloudinary account per Shopify store.

### Get your account details

You'll need your Cloudinary cloud name to build delivery URLs for your Shopify assets.

**To find your cloud name:**

1. Go to the developer [Dashboard](https://console.cloudinary.com/app/home/dashboard) of your product environment.
2. Copy the **Cloud name**. Record this value for use in the theme setup.

> **TIP**:
>
> We recommend changing your cloud name to something memorable, such as your site name, since the cloud name appears in every delivery URL you build. You can edit the cloud name if you have fewer than 1000 files in your account. Use the **Edit** option in the product environment's 3-dots menu.
> If you're on an Advanced plan or above, you may be eligible for a custom hostname (e.g., `media.yourdomain.com`) instead of using the standard Cloudinary URL format.

### Test Cloudinary URL structure

To test delivering an optimized, resized image or video, take a URL from your store and test it.

> **NOTES**:
>
> * You must use `<your_cloud_name>/video` or `<your_cloud_name>/image` in the prefix, depending on which file type you want to optimize and deliver.

> * The transformations shown in the examples below are just suggestions. You can customize the transformation parameters based on your specific needs. For example, you may want different image sizes, video resolutions, aspect ratios, or quality settings. For a complete list of available transformations, see the [Transformation URL API reference](transformation_reference).

#### Images

Given an image URL from your store in one of these formats:

```
https://cloudinary-delivery-only-demo.myshopify.com/cdn/shop/files/gift_card.png?v=12345&width=1000
```

Or:

```
https://cloudinary-delivery-only-demo.myshopify.com/cdn/shop/files/gift_card_1000x.png
```

If you want optimized delivery with width 1000, you'll need to convert the Shopify image URL to:

```
https://res.cloudinary.com/<your_cloud_name>/image/upload/c_scale,w_1000/f_auto/q_auto/shop/files/gift_card.jpg
```

Where:

* `c_scale,w_1000` - Scales the image to a width of 1000 pixels while maintaining aspect ratio
* `f_auto` - Automatically delivers the optimal image format based on the browser
* `q_auto` - Automatically applies the optimal quality compression

You can also apply creative transformations dynamically. For example, to change a portrait image to landscape using generative fill:

```
https://res.cloudinary.com/<your_cloud_name>/image/upload/ar_16:9,b_gen_fill,c_pad,/f_auto/q_auto/shop/files/gift_card.jpg
```

Where:

* `ar_16:9` - Sets the aspect ratio to 16:9
* `b_gen_fill` - Uses AI generative fill to seamlessly extend the background
* `c_pad` - Pads the image to fit the new aspect ratio

#### Videos 

Given a video URL:

```
https://cloudinary-delivery-only-demo.myshopify.com/cdn/shop/videos/c/vp/d240800310164d0c930654d4826912b6/d240800310164d0c930654d4826912b6.HD-1080p-2.5Mbps-61155085.mp4?v=0
```

Replace it with the optimized delivery URL. Note that you want to use original videos with Cloudinary, so replace `/c/vp` with `/c/o/v` and remove the Shopify-processed video file name:

```
https://res.cloudinary.com/<your_cloud_name>/video/upload/ac_none/c_limit,h_1080/f_auto/q_auto/shop/videos/c/o/v/d240800310164d0c930654d4826912b6.mp4
```

Where:

* `ac_none` - Disables audio codec transformation, keeping the original audio
* `c_limit,h_1080` - Limits the height to 1080 pixels (won't upscale if the video is smaller)
* `f_auto` - Automatically delivers the optimal video format
* `q_auto` - Automatically applies the optimal quality compression

## Stage 2: Shopify Theme setup

### Add Cloudinary settings to theme configuration

Set Cloudinary Image and Video hostnames as theme variables in your Shopify Theme settings (`settings_schema.json`).

Edit the `settings_schema.json` and add the following global theme settings:

```json
{
   "name": "Cloudinary Image and Video",
   "settings": [
     {
       "type": "checkbox",
       "id": "optimize_with_cloudinary",
       "default": true,
       "label": "Optimize images and videos with Cloudinary"
     },
     {
       "type": "text",
       "id": "cloudinary_image_prefix",
       "default": "https://res.cloudinary.com/<your_cloud_name>/image/upload/",
       "label": "Cloudinary image prefix"
     },     
     {
       "type": "text",
       "id": "cloudinary_video_prefix",
       "default": "https://res.cloudinary.com/<your_cloud_name>/video/upload/",
       "label": "Cloudinary video prefix"
     },
    {
      "type": "text",
      "id": "cloudinary_image_default_transformation",
      "default": "c_limit,w_1000/f_auto/q_auto",
      "label": "Cloudinary image transformation"
    },
    {
      "type": "text",
      "id": "cloudinary_video_default_transformation",
      "default": "ac_none/c_limit,h_1080/f_auto/q_auto",
      "label": "Cloudinary video transformation"
    }
   ]
 }
```

### Add the cloudinary-url snippet

Add the `cloudinary-url.liquid` snippet to the `/snippets/` directory of your theme. This snippet enables you to replace Shopify image and video URLs with Cloudinary URLs throughout your theme files.

The recommended approach is to wrap existing media tags with the `capture` Liquid tag and then render the `cloudinary-url` snippet on the captured content. For example, if your original theme has:

```liquid
<picture>
  ...{code creating the picture tag}
</picture>
```

You would wrap it as follows:

```liquid
{%- capture picture_content -%}
  <picture>
    ...{code creating the picture tag}
  </picture>
{%- endcapture -%}
{%- render 'cloudinary-url', content: picture_content -%}
```

For implementation examples showing how to use the `cloudinary-url` snippet in different themes, see the [cloudinary-shopify-theme-delivery](https://github.com/cld-et/cloudinary-shopify-theme-delivery/tree/main/delivery-only) repository.

### Enable preconnect for performance

In your theme's global files, add a preconnect link to the `<head>` section of your HTML files. This ensures that the browser connects to the Cloudinary CDN as the page render starts, which helps boost LCP (Largest Contentful Paint) performance:

```html
<link rel='preconnect' href='https://res.cloudinary.com' />
```

> **NOTE**: If you're using a custom CNAME for Cloudinary delivery, replace `https://res.cloudinary.com` with your custom domain (e.g., `https://media.yourdomain.com`).

The preconnect header prevents the additional CDN handshake from impacting performance.

## Get help

For additional assistance with your implementation, [contact Cloudinary support](https://support.cloudinary.com/hc/en-us/requests/new).