Skip to main content

Add Product Image

POST 
/api/products/:product/images

Add a new image to a product. The image field accepts EITHER an uploaded file (multipart/form-data) OR a URL / base64 string (application/json).

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Mode 1 — File upload (multipart/form-data):

  • image (required, file): image file uploaded from the device. Allowed types: jpg, jpeg, png, gif, webp. Max size: 10 MB (10240 KB).

Mode 2 — URL or base64 string (application/json):

  • image (required, string): image URL or base64 encoded data URI.

Common optional fields (both modes):

  • name (optional, max 255): image display name
  • sort_order (optional, integer): display order
  • is_primary (optional, boolean): set as the primary product image
  • download (optional, boolean): URL mode only — if true, downloads and stores the image from the URL
  • swatch_variant_attribute (optional, max 255): marks this image as the variant swatch for the named variant attribute (e.g. "color"). Sales channels that support swatches render it as the variant's swatch image. Omit or send null for a normal gallery image.

Request​

Responses​

OK

Response Headers
    Content-Type