> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Shopify integration (Debut theme)

> Learn how to add dynamic product images to your Shopify store using the Debut (Vintage) theme and Uploadcare’s jQuery File Uploader.

> **Note**
>
> **Note:** This guide covers the legacy jQuery-based File Uploader, deprecated as of September 2025. For current integrations, use `@uploadcare/file-uploader` instead, see [File Uploader](/docs/file-uploader/).

This guide covers adding customizable products to a [Shopify](https://shopify.com)
store by integrating [jQuery File Uploader](/docs/uploads/file-uploader/) to allow
product customizations. We'll use [image processing operations](/docs/transformations/image/#image-transformations-list)
to render resized image previews of your customized Shopify products.

We are using the Debut "vintage" theme in this guide.
If you want to use the new Dawn theme, check the latest version
of [Shopify guide](/docs/integrations/shopify/).

[Shopify](https://shopify.com) is an eCommerce platform that allows you to build
online stores. However, you can add static item images only for your items.
Uploadcare can help you create custom print sweatshirts, mugs with a logo, etc.

Specifically, we'll be building a product page for a customizable poster print:

![Shopify product page](https://ucarecdn.com/69d6a886-654a-4b09-8559-bc0e1971c5d0/-/preview/ "We can now see the elements we've added to this guide")

A user uploads an image of a future poster and will see a product preview
updated in real-time. We have added a condition that if the user hasn't
selected an image, he will not be able to add the poster to the cart.

Let's get started.

* [Before we begin](#preparations)
  * [Shopify](#preparations-shopify)
  * [Uploadcare account](#preparations-uc)
* [Step 1. Setting up the product](#setting-up-the-product)
* [Step 2. Adding the uploading widget](#adding-file-uploader)
* [Step 3. Live product preview](#live-product-preview)
* [Step 4. Preview in the cart](#cart-preview)
* [Results](#results)
* [Conclusion](#conclusion)

## Before we begin \[#preparations]

### Make a Shopify account \[#preparations-shopify]

If you don't have one yet, create a Shopify account. It's free for 14 days.
We'll go with the [Debut theme](https://themes.shopify.com/themes/debut/styles/default/) (this is a "vintage" theme,
so the templates for it are different for other themes), but you can pick
anyone you like. 🦄

### Create an Uploadcare account \[#preparations-uc]

Same here: if you aren't with us yet, [sign up](https://app.uploadcare.com/accounts/signup/). Once you have
an account, navigate to your [Dashboard](https://app.uploadcare.com/) to create a new
[Project](/docs/start/settings/) or discover [API keys](https://app.uploadcare.com/projects/-/api-keys/) for an
existing one. To go through the steps of this guide, you will need the [Public API Key](/docs/start/settings/#keys-public), which tells Uploadcare which project your file
uploads should go to.

![A screenshot of Uploadcare project dashboard](https://ucarecdn.com/7b4a586e-9ece-4233-8e03-d1c47d3509f6/-/preview/ "You can easily grab the Public API key from the project's dashboard")

All files added by users will be stored in [Uploadcare storage](/docs/uploads/storage/).
You can view them in the [Dashboard](https://app.uploadcare.com/) on the File tab.

## Step 1. Setting up the product \[#setting-up-the-product]

Navigate to the Shopify admin panel to create your product. Go to the
**Products** section and hit the **Add product** button. Fill out all
the necessary fields such as product name, description, price, etc.
Now, let's use Shopify's built-in uploader to upload a product image.

Click **Add media from URL** and upload a poster template image
from a URL or you can upload a picture directly.

Note that the product image must have a transparent area,
which will be “filled” with the loaded image.

![Shopify's product editor page](https://ucarecdn.com/52da3b63-9809-4dac-b688-270c1bcb294d/-/preview/ "Add images from your Uploadcare Project via URL.")

Fill in the inventory to add the item to the cart later.
Also, make sure that **Product Status** is set to **Active** to appear
in the store. Click **Save** to apply the changes.

### Adding tags

Add a `customizable` tag to the Tags field. If the product doesn't
have a `customizable` tag, the widget will not add to it.
Click **Save** to apply the changes.

### Disable the image zoom effect

You'll also need to disable the image zoom effect for the uploaded product
pictures to ensure our customized products will work correctly. Go to the
**Online store** → **Theme** → **Сustomize**. Instead of Home at the top
of the page, select a Product. Hit **Product pages** in the sidebar
and uncheck **Enable image zoom**. This way, Shopify won't interfere
with our upcoming image resize feature.

![Shopify Image Zoom](https://ucarecdn.com/8cc0dd44-a8a5-4bcb-a486-55c68687dc38/-/preview/ "Turn off Shopify image zoom")

### Disable cart notification

Go to the **Online store** → **Theme** → **Сustomize**. Instead of Home
at the top of the page, select a Product, and hit **Product pages**
in the sidebar. Hit at the bottom of the sidebar **Theme settings** and
uncheck **Show notification when item is added to cart**.

We've just added a product to your shop! 🚀 Now, let's make it customizable.

## Step 2. Adding the uploading widget \[#adding-file-uploader]

Now, we'll need some prints to customize. Your users will upload them, so we
need to add the uploading widget by including the Uploadcare library.

Shopify allows modifying themes, so let's add some code. It's pretty simple:
go to the **Online store**, hit **Themes**, **Customize**, and select
**Edit code** in the menu on the top of the page. Create a new file in the
**Snippets** section. Name it `uploadcare-settings.liquid`, and add the
uploader `<script>` element followed by another element containing
[your public API key](/docs/start/settings/#keys-public):

This package is deprecated. For new integrations, install `@uploadcare/file-uploader` instead, see [installation](/docs/file-uploader/installation/).

Add another snippet named `uploadcare-fields.liquid`. We'll be adding
an `<input>` element that'll become the uploader button. Put the following
lines in the snippet:

```html
<p class="cart-attribute__field uploader-dawn">
  <input
    id="uploader"
    type="hidden"
    data-images-only="true"
    data-crop="5:7"
    role="uploadcare-uploader"
    name="properties[Upload]"
  />
</p>
```

As you see, our `<input>` comes with some attributes. Here's what they do:

* `data-images-only` tells the uploading widget to accept images only.
  See more about the [images-only option](/docs/uploads/file-uploader-options/#option-images-only).
* `data-crop` defines the aspect ratio of the uploading widget
  [crop option](/docs/uploads/file-uploader-options/#option-crop). Here we enable image cropping
  in the uploader with `data-crop="5:7"`. In this case, 5:7 represents
  the ratio of the transparent area in the product image template.
  It may be different for your product.
* `name="properties[Upload]"` link the Uploader with a custom property
  named `Upload`. As a result, a CDN URL of the uploaded file will be
  saved on Shopify's end and attached to the order. We'll access it
  from within the Cart and other pages.

Add the following lines to the `theme.liquid` file placed in the **Layout**
section right before the closing `</head>` tag:

```html
{% if template == 'product' %}
    {% include 'uploadcare-settings' %}
{% endif %}
```

Discover the `product-template.liquid` file under the **Sections** category,
find the `<form>` element, and put the following somewhere within it:

```html
{% if product.tags contains 'customizable' %}
  {% include 'uploadcare-fields' %}
{% endif %}
```

We're using the `if` statement to render the uploader only on products
that have been tagged as `customizable`.

In this example, we decided to put the snippet right before the variants
selector dropdown like in the screenshot below:

![Shopify's code editor](https://ucarecdn.com/da2332f8-db8a-470a-b1a3-01d1ff4069b9/-/preview/ "A snippet placed into the Shopify template code")

There you go! You've just added the uploading widget to your product page.
Users can now add their prints; our next step will show them a poster
preview.

## Step 3. Live product preview \[#live-product-preview]

Add settings that will allow us to preview our product to be generated once
an image has been uploaded. We can accomplish that using some JavaScript
and [jQuery File Uploader API reference](/docs/file-uploader-api/widget/).

Create a new file in the **Snippets** section. Name it
`uploadcare-customizable-product.liquid`, and add the `<script>`:

This uses the deprecated jQuery Widget API. For new integrations, use @uploadcare/file-uploader instead.

Note that the class names of the elements in your theme may be different.
Use developer tools to find the actual selectors in your theme.
Also, the values of the `backgroundSize` and `backgroundPosition` parameters
need to be adjusted to your product image and the actual position and
size of the transparent area.

Add this snippet to `product-template.liquid`. It's better to place
it at the bottom before the `schema` section:

```html
{% if product.tags contains 'customizable' %}
  {% include 'uploadcare-customizable-product' %}
{% endif %}
```

## Step 4. Preview in the cart \[#cart-preview]

We stored CDN URLs of uploaded images in a dedicated property
and can render previews of customized products on the Cart page.
In `cart-template.liquid` find the cart image wrapper.
In the Debut theme it looks like this:

```html
<div class="cart__image-wrapper">
	<img class="cart__image{% if item.image == null %} hide{% endif %}" src="{{ item | img_url: 'x190' }}" alt="{{ item.image.alt | escape }}" data-cart-item-image>
</div>
```

Replace it with the following lines:

```html
<div class="cart__image-wrapper">
	{%- if item.properties.Upload != blank -%}
		<img class="custom-product-preview cart__image{% if item.image == null %} hide{% endif %}" src="{{ item.image | image_url }}" alt="{{ item.image.alt | escape }}" data-image-upload="{{ item.properties.Upload }}" data-cart-item-image>
	{%- else -%}
		<img class="cart__image{% if item.image == null %} hide{% endif %}" src="{{ item.image | image_url }}" alt="{{ item.image.alt | escape }}" data-cart-item-image>
	{%- endif -%}
</div>
```

As a result, if there's a URL in the Upload property, Shopify will
add it as a data attribute (data-image-upload) to the corresponding
preview image. Also, it will add the `custom-product-preview` class
to this image. To make use of this attribute, we need to add some
JavaScript.

Create a new file in the **Snippets** section. Name it
`uploadcare-cart-preview.liquid`, and add the `<script>`:

```html
<script>
  var previews = document.querySelectorAll(".custom-product-preview");
  previews.forEach(function(preview) {
    var background = preview.getAttribute("data-image-upload");
    preview.style.background = "url(" + background + "-/preview/" + ")";
    preview.style.backgroundSize = "53% 50%";
    preview.style.backgroundPosition = "48% 37%";
    preview.style.backgroundRepeat = "no-repeat";
  });
</script>
```

The script will take all images of the `custom-product-preview` class
and set the CDN URL from the data-image-upload attribute as
a background — the same as we did on the product page.

You can also apply the same changes to Shopify email templates, for instance,
to the order confirmation email (**Store settings** → **Notifications** →
**Order confirmation**).

## Results

If everything is correct, your product page should now look like this:

![Shopify Product Page](https://ucarecdn.com/9fe8feac-7280-471b-be63-431e0051719f/-/preview/ "We can now see the elements we've added in this guide")

You should now see the uploaded image and custom product fields:

![Shopify Cart Page](https://ucarecdn.com/205b6f9e-46a3-4bf5-bd7d-8d97e2992993/-/preview/ "We can now see the uploaded image used as a custom product picture")

## Conclusion

Yay! You have just created a customizable product. The flexibility of Uploadcare
is now enhancing your Shopify store.