> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/digital-asset-management-dam/plugins-and-connectors/plugins/shopify.md).

# Shopify

### Introduction <a href="#introduction" id="introduction"></a>

Scaleflex DAM for Shopify connects your Shopify store to your Scaleflex DAM library. From inside the Shopify Admin, you open the Scaleflex Asset Picker and attach images and videos straight to Products, Collections, and Blog posts — no manual downloads or duplicate uploads.

#### Key features <a href="#key-features" id="key-features"></a>

* Attach DAM images and videos to one or many Products at once, without replacing existing media.
* Set Collection images and Blog post featured images from the DAM.
* Assign DAM images to product variants.
* Fill the Shopify alt text automatically from a DAM metadata field.
* Resize, crop, or pad images on the Scaleflex CDN before they reach Shopify, with one preset per content type.
* Import existing Shopify media back into the DAM.
* Review every attachment in the Sync history.

#### Requirements <a href="#requirements" id="requirements"></a>

* A Shopify store, and permission to install apps on it.
* A Scaleflex DAM account.
* A **security template key** and a **project token** from your Scaleflex project. Each Shopify store uses its own credentials, so several stores can connect to the same or different DAM projects.

### Installation <a href="#installation" id="installation"></a>

1. Open the [**Scaleflex DAM Picker**](https://apps.shopify.com/scaleflex-dam-picker) app listing and click **Install**.

   <figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FAiJaMslM759WMLKGIXnV%2Fimage.png?alt=media&amp;token=faeefe5a-37fc-49f9-926a-8cff70a6b619" alt=""><figcaption></figcaption></figure>
2. Select the Shopify store to install the app on.
3. Review the permissions the app requests and click **Install** to approve them.
4. Shopify opens the app's **Home** page. The app now appears under **Apps** in the Shopify Admin sidebar.

The app requests these permissions:

| Permission                          | Used for                                                  |
| ----------------------------------- | --------------------------------------------------------- |
| Read and write products             | Listing products, attaching media, setting variant images |
| Read and write online store content | Collection images and Blog post featured images           |
| Write files                         | Uploading media to Shopify Files                          |

The app also adds an **Add DAM Assets** link to the **More actions** menu of every product page in the Shopify Admin. See Managing a single product's media.

### Configuration <a href="#configuration" id="configuration"></a>

The app needs a security template key and a project token before you can pick assets. Until both are saved, every page shows a warning with a **Go to Settings** button.

#### Get your Scaleflex credentials <a href="#get-your-scaleflex-credentials" id="get-your-scaleflex-credentials"></a>

1. Sign in to the Scaleflex Hub and open the project you want to connect.
2. Create a security template (or reuse one) and copy its **key**. It must allow listing and reading files; also allow uploads and folder creation if your team uploads from the picker or uses **Import to Scaleflex**.
3. Copy the **project token**.

#### Connect the app <a href="#connect-the-app" id="connect-the-app"></a>

1. In the app, open **Settings**.
2. Paste the **Security template key** and the **Project token**.
3. Adjust the optional settings below if needed, then click **Save**.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2F4UL1EQLAlFIOUlnMl9tH%2Fimage.png?alt=media&amp;token=506815a2-63cc-4da4-b6ed-676c37f1fcc8" alt=""><figcaption></figcaption></figure>

| Setting                                      | Required                  | What it does                                                                                                                                                                                          |
| -------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Security template key                        | Yes                       | Authenticates the Asset Picker with your DAM.                                                                                                                                                         |
| Project token                                | Yes                       | Identifies your Scaleflex project.                                                                                                                                                                    |
| Directory                                    | No                        | Restricts the Asset Picker to one folder, e.g. `/marketing/banners/`. Users can't browse outside it. Also the target folder for **Import to Scaleflex**. Leave blank to allow the whole library.      |
| Remove the version hash (vh) from asset URLs | No (on by default)        | Strips the `?vh=…` parameter from DAM URLs before they are sent to Shopify.                                                                                                                           |
| Alt text source                              | No (default: Description) | The DAM metadata field copied into the Shopify alt text. Title and Description are always offered; once a project token is entered, your project's custom text fields are listed too.                 |
| Asset Picker config (JSON)                   | No                        | Advanced Asset Picker options, merged into the app's defaults. Authentication can't be overridden here. See the [Asset Picker docs](https://scaleflex.github.io/asset-picker/#/docs/getting-started). |
| Uploader config (JSON)                       | No                        | Advanced options for the uploader inside the picker, e.g. `{"targetFolder": "/Example"}`. See the [Uploader docs](https://scaleflex.github.io/uploader/#/docs/getting-started).                       |

Changes to the alt text source apply to media attached from then on. Existing media keeps its alt text.

#### Image presets <a href="#image-presets" id="image-presets"></a>

Image presets resize or crop images on the Scaleflex CDN before Shopify receives them, so every image of a kind has the same size. Each content type has its own preset; videos, GIFs, and SVGs are never transformed.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FImGANOsZuuN2dgLgbpv5%2Fimage.png?alt=media&amp;token=6fc26f76-fa8a-4789-83e4-4b2b4cdb23c8" alt=""><figcaption></figcaption></figure>

| Content type | Applies to                 | Suggested size |
| ------------ | -------------------------- | -------------- |
| Products     | Product and variant images | 2048 × 2048 px |
| Collections  | Collection images          | 1920 × 1080 px |
| Blog posts   | Blog post featured images  | 1200 × 630 px  |

For each preset, pick a **Transform** mode:

* **Off** — upload the original image as it is in the DAM.
* **Crop to size** — crop to exactly the width and height, centered.
* **Fit inside size, pad with a background** — scale to fit, and fill the rest with a background color (white by default).
* **Resize to fit, keep proportions** — scale down to fit within the size, without cropping.

When a mode is on, you can also set **Quality (1–100)** and **Extra CDN parameters** as a query string, e.g. `gravity=auto&sharp=1` (see the [Cloudimage docs](https://docs.cloudimage.io)). Smaller images are never enlarged. Presets apply to images attached after you save.

### Attaching media to products <a href="#attaching-media-to-products" id="attaching-media-to-products"></a>

DAM media is always added to a product's existing media — nothing already on the product is replaced. Each asset's alt text is filled from the DAM field chosen in **Settings**, and the product's image preset is applied.

#### Attach media to several products at once <a href="#attach-media-to-several-products-at-once" id="attach-media-to-several-products-at-once"></a>

1. Open **DAM Media to Products** in the app menu.
2. Find products with the search box, or filter by **Status** (Active, Draft, Archived, Unlisted) and **Vendor**.
3. Tick the products to update. Your selection is kept when you change pages or search again.

   <figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FaIfHK1KIGQSfeZ007sBM%2Fimage.png?alt=media&amp;token=32dbb7b5-1acb-4279-9555-77af699a371a" alt=""><figcaption></figcaption></figure>
4. Click **Attach DAM media** in the table's bulk actions, or **Open Asset Picker** in the selection card.
5. In the Asset Picker, select one or more images or videos and confirm.

   <figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FCt4nLozGCJz1FIj19iS9%2Fimage.png?alt=media&amp;token=b434af82-b2c4-4144-80d3-88feabef01e6" alt=""><figcaption></figcaption></figure>
6. Follow the **Attach progress** card. Each product shows **Attached** or the error. If some failed, click **Retry failed** to try those products again with the same assets.

#### Managing a single product's media <a href="#managing-a-single-products-media" id="managing-a-single-products-media"></a>

Open a product's media page in either of two ways:

* In the app's product list, click **View media** on the product's row.
* On the product page in the Shopify Admin, open **More actions** and click **Add DAM Assets**.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FSajMirC5V0kqp7sGEK3v%2Fimage.png?alt=media&amp;token=d4e81579-abfa-43f5-8ffe-07445e2824b2" alt=""><figcaption></figcaption></figure>

On this page, you can:

* **Add media** — click **Add DAM Assets** and pick assets. New media shows a placeholder for a few seconds while Shopify processes it.
* **Edit alt text** — change the text next to an image and click **Save**.
* **Reorder** — drag a row by its ⠿ handle, then confirm. The app warns you that a manual order overrides the order defined in the DAM.
* **Delete** — tick one or more items and click **Delete selected**. If an image is used by a variant, it is removed from that variant too.
* **View in Shopify admin** — jump to the product in the Shopify Admin.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FAQm7QrIfeKPwL4vP0e2N%2Fimage.png?alt=media&amp;token=c65a740e-9228-4d56-87f2-2bfffde87397" alt=""><figcaption></figcaption></figure>

#### Product position from the DAM <a href="#product-position-from-the-dam" id="product-position-from-the-dam"></a>

If an asset has a **Product Position** set in the DAM, the app asks before attaching it, because it will move to that position in the product's media.

* **Add and reorder** — attach the asset and move it to its DAM position.
* **Add without reordering** — attach it at the end, like any other asset.
* **Cancel** — attach nothing.

#### Variant images <a href="#variant-images" id="variant-images"></a>

Products with more than one variant show a **Variant images** card under the media list. Each variant shows one image.

* **One variant** — under **Variants**, click **Choose image** (or **Change**) on the variant. Click **Remove** to clear it.
* **All variants sharing an option** — under **Assign by**, pick an option such as Color, then click **Choose image** next to a value such as Red.

In the image dialog, click one of the product's images, or click **Pick from Scaleflex DAM**. A DAM image is first added to the product, then assigned once Shopify has processed it. Only images can be used for variants, not videos.

### Collection and Blog post images <a href="#collection-and-blog-post-images" id="collection-and-blog-post-images"></a>

A collection has one image, and a blog post has one featured image. Picking a DAM image sets it, or replaces the current one. Only images can be picked here, one at a time.

1. Open **DAM Media to Collections** or **DAM Media to Blog Posts** in the app menu.
2. Search for the collection or blog post, and click its title.
3. In the card that opens below the list, click **Set image** (or **Replace image**).
4. Pick an image in the Asset Picker and confirm.
5. Optionally edit the **Alt text** (up to 255 characters) and click **Save**.

### Importing Shopify media into Scaleflex <a href="#importing-shopify-media-into-scaleflex" id="importing-shopify-media-into-scaleflex"></a>

**Import to Scaleflex** copies the media already in your store into your DAM, so it can be managed and reused from one place. It uploads every image and video on your Products, Collections, Blog posts, and Files into the **Directory** set in Settings.

1. Open **Import to Scaleflex** in the app menu.
2. Click **Sync all store media to Scaleflex**.
3. The import runs in the background. You can leave the page and come back later; the list refreshes on its own while items are pending.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2Fj6uz3Wij7Pui1HQUYIsI%2Fimage.png?alt=media&amp;token=908c44b7-cd70-4e92-9adf-e048cea5b43c" alt=""><figcaption></figcaption></figure>

The tabs filter items by status: **Pending**, **Synced**, **Failed,** and **Skipped**. Files already synced are skipped when you run the import again.

* **View in Scaleflex** — preview a synced item in the DAM.
* **View error** — see why an item failed. From there, click **Skip this file** to stop retrying it.
* **Retry failed** — try every failed item again.
* **Skip selected** — tick failed items and skip them all at once.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FmKV2gLlh5Hcx8TLspVeN%2Fimage.png?alt=media&amp;token=929123bb-e4ff-4458-bd2c-8f6f5b60bd09" alt=""><figcaption></figcaption></figure>

### Tracking activity <a href="#tracking-activity" id="tracking-activity"></a>

#### Sync history <a href="#sync-history" id="sync-history"></a>

**Sync history** lists the latest 50 attach operations, newest first. Each row shows the resource, its type (Product, Collection, Blog post or File), the number of media, the status and the time.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2F4QmgvNSozbTwZ7t0sATF%2Fimage.png?alt=media&amp;token=ca66f5d1-b85e-40da-8a43-5c1bd8217dd6" alt=""><figcaption></figcaption></figure>

Click **View** on a row to see each media item of that operation: its thumbnail, name, alt text and status. A badge shows any transform applied, such as **Cropped 2048×2048**. For a failed item, click **View error** to read the reason.

#### Home dashboard <a href="#home-dashboard" id="home-dashboard"></a>

The app's **Home** page gives an overview of your setup and usage:

* **Asset usage** — the number of DAM assets attached through the app (split into images and videos), and the number of Shopify media imported into the DAM.
* **Setup status** — whether the security template key and project token are set, and whether the picker is restricted to a directory.
* **Browse your library** — an inline Asset Picker to browse the DAM without leaving Shopify.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FtldeFByZehgp6etBbKBP%2Fimage.png?alt=media&amp;token=1c293753-d8fe-4946-a90d-6f5f99067120" alt=""><figcaption></figcaption></figure>

### FAQ and troubleshooting <a href="#faq-and-troubleshooting" id="faq-and-troubleshooting"></a>

**The Asset Picker buttons are disabled, and a yellow warning is shown.** The security template key or project token is missing. Open **Settings**, enter both, and click **Save**.

**Does attaching media replace the product's existing images?** No. Media is always added after the existing media. Only collection images and blog post featured images are replaced, since each holds a single image.

**Which file types can I attach?** Images and videos for products. Collections, blog posts, and variants accept images only.

**A new image shows a placeholder instead of a preview.** Shopify processes new media for a few seconds before showing it. The app refreshes the list on its own; reload the page if it still shows a placeholder.

**I changed the alt text source or an image preset, but my existing images didn't change.** Both settings apply only to media attached after you save. Edit the alt text of existing media on the product's media page, or attach the image again.

**Can I crop an image in the picker before attaching it?** Yes, if the picker's export options are enabled in **Asset Picker config (JSON)**. The cropped version is sent to Shopify, and Sync history shows it with a **Cropped** badge. See the [Asset Picker docs](https://scaleflex.github.io/asset-picker/#/docs/getting-started) for the options.

**Why is the attach order different from the order I picked?** Assets with a **Product Position** in the DAM move to that position when you choose **Add and reorder**. Choose **Add without reordering** to keep them at the end.

**Can several Shopify stores use the same DAM?** Yes. Each store saves its own credentials, so stores can share one Scaleflex project or use different ones.
