# Shopify (/docs/shopify)

With a Shopify store connected to a Space, media's files can be tagged with the store's products: which products are in a photo, and where. Editors find files by product, Content's pages can show them as shoppable images, and the Obelism app in Shopify adds the files to the products themselves.

A Space has one store, connected on www by an admin or developer. Content's [Shopify guide](https://content.obelism.studio/docs/guides/shopify#connecting-a-store) shows how.

## Tagging products [#tagging-products]

**Products** in a file's details opens the file's products:

1. **Find a product** searches the store's products by title. **Add** tags the file with it.
2. **Place** a product, then click the image where it is. A product's point is `{ x, y }`, fractions of the width and height from the top left, like the focal point, so it holds at every size and crop. A product without a point says only that it is in the picture.
3. **Remove** untags it.

A file has up to 50 products. The **Products** filter above the library lists the tagged products by how many files have them, and finds every file with one: "every photo with this jacket".

- A product deleted in Shopify loses its tags.
- While the Space has no store connected, tags stay but are hidden; they come back when the store is connected again.
- A changed handle isn't followed: the product's id is what counts.

## Suggestions [#suggestions]

media can suggest the products it sees in an image. **Find products** in a file's products asks; new JPEG, PNG, GIF, WebP and AVIF uploads are looked at by themselves.

The first time, the store's catalog is indexed first, which takes a few minutes; try again after. After that the index follows the store's product changes.

Each suggestion shows how sure it is and where the product was found. **Accept** tags it there, **Place and accept** lets you click where it is first, and **Dismiss** removes it for good. Nothing is tagged without an editor accepting it, and suggestions below 60% sure aren't shown.

Suggestions run on Cloudflare Workers AI: the image is described and compared with the store's products, and a vision model checks which of them are in it.

## Showing products on a site [#showing-products-on-a-site]

A use of a file in Content can show its products: **Show its products** on a picked file, or `products: true` in the field's value. Delivery then adds `products` (`id`, `handle` and `position`) to that asset. How they are shown, hotspots on the points or a list next to the image, is up to your site. See [products in a file](https://content.obelism.studio/docs/guides/assets#products-in-a-file).

## In the Shopify admin [#in-the-shopify-admin]

The Obelism app adds media to a product's page in Shopify:

- **The Obelism media block** lists the files tagged with that product. **Add to product** adds one to the product's media. A file already on the product says so; one that changed in media since is marked **Changed in Obelism**, and **Update** brings the change over.
- **Add from Obelism media**, under **More actions**, opens the Space's whole library, by folder and search, to add any image or video to the product.

Staff of the store need no Obelism account for this: it adds the Space's files to products, never changes them in media. Shops connected before these features have to approve the new permissions (files, products and translations) once, by opening the Obelism app from **Apps**.

### What an import does [#what-an-import-does]

- A file is imported into a store **once**. Adding it to another product links the same Shopify file instead of uploading it again; a file deleted in Shopify is imported anew the next time.
- Its alt text comes along in the store's primary language, and in the store's other published languages as translations. After the import the translations are the merchant's: nothing overwrites them.
- The file's other tagged products are offered, not added: a photo with a jacket and a bag lands on the bag's page only when you add it there.
- **Update** replaces the image in Shopify and its alt text, keeping its Shopify URL and its products. Nothing is pushed to the store without someone choosing to.

JPEG, PNG, GIF and WebP images import, and MP4, MOV and WebM videos up to 1 GB. A video shows **Processing in Shopify** until Shopify has processed it, and **Update** changes only its alt text.

### Shoppable images in the theme [#shoppable-images-in-the-theme]

Importing or updating a file writes its placed products to a product metafield, `$app:obelism.hotspots`. The app's **Shoppable image** theme block, for product templates, reads it and draws a hotspot on each product, linking to its page. Its settings: **Show product names**, **Hotspot color** and **Hotspot text color**. Add it in the theme editor where it should go.

The metafield follows the tags only when a file is imported or updated: tag a new product in media, then **Update** in Shopify.