How to Send Processed Images Back to Shopify

01

Define the writeback contract before calling GraphQL

A processed image can become the new primary product image, an additional gallery image, a variant-specific image, or merely a draft asset waiting for approval. Those are different catalog changes. Put the intended action in the job record instead of making the upload node guess from filename order.

Use Shopify’s GraphQL product ID as the catalog identity. A handle can change, a title is not unique, and an SKU often belongs to a variant rather than the product itself. If the source system starts from SKU, resolve SKU to variant and product once, then store both IDs on the processing job.

{
      "jobId": "shopify_912855135_media_853695510_catalog-v3",
      "productId": "gid://shopify/Product/912855135",
      "variantIds": ["gid://shopify/ProductVariant/44710001"],
      "sourceMediaId": "gid://shopify/MediaImage/853695510",
      "action": "replace_gallery_slot",
      "targetPosition": 0,
      "recipeVersion": "catalog-v3"
    }

02

Use Shopify’s current media path

For new integrations, use the GraphQL Admin API. Shopify marks the REST Admin API as legacy and points apps toward GraphQL. The app needs the appropriate product and file scopes, and the merchant user still needs permission to update those resources. Shopify’s current product media guide lists the required scopes and supported flow.

Take that snapshot immediately before the write, not when the image entered the processing queue. A merchant may reorder or replace photos while your job is running. If the current media state no longer matches the expected source version, stop for review instead of confidently applying yesterday’s plan to today’s product.

03

Give Shopify an image it can actually ingest

A BackgroundErase multipart response is binary image data. Shopify’s product media mutations commonly accept an originalSource URL, so the no-code-friendly route is to upload the processed file to durable object storage first and give Shopify a URL it can fetch without your workflow’s private headers. Keep that object available until Shopify finishes processing.

If the workflow needs to send file bytes directly into Shopify’s file system, use stagedUploadsCreate, upload the file to the returned temporary target with every supplied parameter, and then create the file or product media from the resulting resource URL. Shopify documents this secure two-step flow in the official stagedUploadsCreate reference and fileCreate reference.

04

Add the processed image asynchronously

The simplest GraphQL path for an existing product is productUpdate with a media input. Send the product ID, the processed image URL, media content type, and intentional alt text. Shopify uploads and associates the media asynchronously, so the mutation response is the beginning of the handoff, not the end. The current behavior is documented in Shopify’s productUpdate reference.

mutation AddProcessedImage(
      $product: ProductUpdateInput!
      $media: [CreateMediaInput!]
    ) {
      productUpdate(product: $product, media: $media) {
        product {
          id
          media(first: 20) {
            nodes {
              id
              alt
              mediaContentType
              preview { status }
            }
          }
        }
        userErrors { field message }
      }
    }

{
      "product": {
        "id": "gid://shopify/Product/912855135"
      },
      "media": [
        {
          "originalSource": "https://assets.example.com/sku-1842/catalog-v3/master.png",
          "alt": "Walnut dining chair on a transparent background",
          "mediaContentType": "IMAGE"
        }
      ]
    }

Check three error surfaces: the HTTP response, top-level GraphQL errors, and mutation-level userErrors. GraphQL can return HTTP 200 while the mutation reports a field or permission problem. Store the returned media ID as soon as it exists. That ID is what later steps reorder, verify, or remove.

05

Wait for Shopify to finish processing

Media ingestion is asynchronous. Poll the returned file or media node until its status is ready, failed, or a sensible deadline is reached. Use increasing delays instead of asking Shopify every second whether it is done. If processing fails, keep the previous product image untouched and retain the stored master so the handoff can retry without rerunning image cleanup.

query CheckProcessedMedia($id: ID!) {
      node(id: $id) {
        id
        ... on MediaImage {
          alt
          status
          image { url width height }
        }
        ... on File {
          fileStatus
        }
      }
    }

06

Preserve order, alt text, and variants

The first product media item typically acts as the primary image across collection cards, search, and thumbnails. If the processed image should become primary, move it to position zero after it is ready. Shopify provides productReorderMedia for changing positions without deleting and recreating the gallery, and the mutation returns a job you can track. See the current productReorderMedia reference.

mutation PromoteProcessedImage($productId: ID!, $mediaId: ID!) {
      productReorderMedia(
        id: $productId
        moves: [{ id: $mediaId, newPosition: "0" }]
      ) {
        job { id done }
        mediaUserErrors { code field message }
      }
    }

Copy or deliberately rewrite alt text. Background removal changes presentation, not product identity, so the original description is often a good starting point. Avoid “processed image,” “transparent PNG,” or the filename as customer-facing alt text. Describe the product and meaningful view instead.

Variant media needs special care. If the old image represents the blue variant and the new media is meant to replace it, update that association after the media is ready. Record the previous mapping first. Removing a file-product association can also clear variant use of that file, so the rollback plan must include variant IDs, not merely gallery position.

07

Make the catalog write safe to replay

The idempotency key should connect the Shopify product, source media version, and cleanup recipe. Store it in your job database and, if useful, a Shopify metafield. On retry, look up the previously created media ID before calling productUpdate again. Filenames are helpful labels but weak uniqueness rules; duplicate uploads and renamed files happen.

A rollback should be a normal job transition, not a panicked manual search. Move the previous media back to its position, restore variant mappings, and mark the processed media as rejected or detached. Delete files only when retention policy says they are no longer needed. Storage is cheap; reconstructing an undocumented product gallery during a campaign is not.

08

Handle Shopify failures without reprocessing the image

Shopify’s GraphQL Admin API uses calculated query cost and returns throttle information in the response extensions. Pace catalog updates from that actual state, and retry throttled or temporary failures with backoff. Shopify’s current limits and response fields are documented in its API limits guide.

Separate image_ready from shopify_published. The first means the processed master exists. The second means Shopify ingested it, the gallery is in the intended order, variant associations are correct, and a final read confirmed the state. If the handoff fails, resume at Shopify. Do not send the source through BackgroundErase again because a catalog mutation had a bad afternoon.