Shopify productCreateMedia is deprecated: use productSet files

Shopify marks productCreateMedia as deprecated and tells you to use productUpdate or productSet instead. If your script attaches AI-generated product images with the old mutation, plan the move now: the replacement for a create-and-attach flow is productSet with a files list, and it has a destructive default you need to know about before you run it on a live product.

Shopify facts come from the productCreateMedia and productSet references, read 2026-10-02. Sume facts come from the Image docs and Media inputs.

What does the deprecated mutation do?

productCreateMedia takes a product id and a list of CreateMediaInput objects. Two fields are required: originalSource, the URL of the media file, and mediaContentType, for example IMAGE or EXTERNAL_VIDEO. alt is optional. It needs the write_products access scope and lets you add several files in one request.

Its error behavior is worth remembering because you may have written code around it: Shopify says it adds all valid files and returns errors for the invalid ones. A partial success was normal, so a script that only checked for an HTTP 200 may already have been dropping files silently.

How does productSet take files?

productSet accepts a files field of type FileSetInput, described as a way to create a product and associate file attachments such as images or videos. Each entry can carry originalSource, alt, filename and contentType, and files can be attached at the product level and at the variant level.

The mutation runs synchronously by default and returns the updated product. Shopify says setting synchronous: false may be better for large or complex inputs and should be used if you see timeouts; the response is then a ProductSetOperation you track. The stated default limit is 2048 variants per product.

What can productSet delete?

This is the trap. For list fields such as variants, collections and metafields, productSet creates new entries, updates existing ones and deletes entries you leave out of the input. For other fields only the ones you include change. A script that sends only a files list and a title is fine for a new product, but if you reuse it on an existing product and also send a short variants list, the missing variants are removed.

If you only want to add images to a product that already exists, read the product first, send its full variant and collection lists back unchanged, or use productUpdate and test on a draft product before you touch a live listing. Shopify's page does not say whether files itself replaces or appends, so confirm that on a development store too.

Where do the image URLs come from?

Sume image responses carry data[].url on media.sume.com, and the docs say integrations should store that URL rather than a provider URL. Reference edits take input_references with an image_url, so a white-background product photo can go in and a staged scene can come out. The call below requests two variants; see the image model catalog for per-model limits on n.

curl -X POST "https://api.sume.com/v1/images" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Place this bottle on a marble bathroom shelf, soft morning light, no text",
    "input_references": [
      { "type": "image_url",
        "image_url": { "url": "https://example.com/bottle-white-bg.jpg" } }
    ],
    "n": 2
  }'
# Each data[].url in the 200 response is a media.sume.com URL.
# Use it as originalSource inside the files list you send to Shopify.

How do I test the migration safely?

Create a draft product on a development store that mirrors a real one: same variant count, same collections, same metafields. Run the new productSet call against it and diff the product before and after. If anything in a list field disappears, your input was incomplete.

Keep generation and migration separate. Generate the images first, hold their Sume URLs, and only then run the Shopify mutation. If the mutation fails, you retry it with the URLs you already have instead of paying for new images; the Errors and rate limits page explains why unsafe submits need an Idempotency-Key. Finally, compare userErrors from the old and new mutation, because the old one returned partial successes and your monitoring may have relied on that shape.

What should I migrate first?

Search your code for productCreateMedia and mediaContentType, then replace each with the smallest change that keeps behavior. Keep a log of Sume job ids next to Shopify product ids so a failed run can be repeated without paying for the images twice. For a pure upload of many files before attaching them, see Shopify fileCreate batches.