Images
Requires scope merchant-items-detail.
Lists one product’s images.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product, as returned by the Merchant API.
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/products/20417/images?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } }, { "id": 88215, "is_primary": false, "position": 1, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides.jpg", "alt": "Pulled chicken and cornbread on the side", "width": 1200, "height": 900, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-card.webp", "w": 480, "h": 360 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-card2x.webp", "w": 800, "h": 600 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-view.webp", "w": 1200, "h": 900 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-wa.jpg", "w": 1080, "h": 810 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides.jpg", "w": 1200, "h": 900 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-wa.jpg", "width": null, "height": null } } ], "has_more": true, "next_cursor": "eyJpZCI6ODgyMTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-items-update.
Attaches a file-manager image to a product.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Attach one image: a media_id from the store's own files, or a PUBLIC url
that the server downloads into the store's files (SSRF-guarded, never
hot-linked). primary: true makes it the main image; otherwise it joins the
gallery.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/products/20417/images" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "url": "https://northwindgoods.example/images/smokehouse-party-pack-sides.jpg", "primary": false }'{ "status": "success", "message": "Image attached", "data": { "id": 88215, "is_primary": false, "position": 1, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides.jpg", "alt": "Pulled chicken and cornbread on the side", "width": 1200, "height": 900, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-card.webp", "w": 480, "h": 360 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-card2x.webp", "w": 800, "h": 600 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-view.webp", "w": 1200, "h": 900 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-wa.jpg", "w": 1080, "h": 810 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides.jpg", "w": 1200, "h": 900 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-sides-wa.jpg", "width": null, "height": null } }}Requires scope merchant-items-update.
Updates a product image, e.g. marking it primary.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product, as returned by the Merchant API.
Identifier of the product image, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Make an image already on the product its primary image. To clear the primary image, DELETE it instead.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/products/20417/images/88214" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "primary": true }'{ "status": "success", "message": "Primary image set", "data": { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "alt": "Smokehouse party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack.jpg", "w": 1200, "h": 1200 } }, "channel_image": { "url": "https://media.usequeek.com/uploads/stores/1095/smokehouse-party-pack-wa.jpg", "width": null, "height": null } }}Requires scope merchant-items-update.
Deletes a product image by media id, or primary for the primary image. Deleting the primary image makes the next image primary; the product is left without one only when it has no other images.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product, as returned by the Merchant API.
Identifier of the product image, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/products/20417/images/88215" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Image removed", "data": { "id": 88215, "deleted": true }}