Skip to navigation

Import product sketches in a batch

Requires products:update. Accepts 1-25 images, up to 25 MB each and 100 MB total for files included in the request. Returns 202 after validating the submission and staging uploaded originals. Downloads, conversion, and final storage run in the background. Poll the returned statusUrl with the same API credential. Each image commits independently; individual failures do not undo successful images. Entries append in submission order unless positions are supplied. Use a batch with one entry for an asynchronous single upload. Supply Idempotency-Key when retrying submissions: the same credential, key, and payload reuse the import; a different payload returns 409. Use a new key to resubmit failed entries. Unfinished imports expire after seven days.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringOptional<=200 characters
Optional key, at most 200 bytes, scoped to the API credential. Reuse only with the same payload.

Request

JSON uses the productSketches array without singular wrappers. Multipart uses repeated field pairs: productSketches[][productId] followed by productSketches[][photo]. Repeat that pair in order for each image.

productSketcheslist of objectsRequired

Response headers

LocationstringOptional
Relative URL of the import status endpoint.

Response

Batch accepted for background processing. Follow Location or statusUrl; this does not mean the images have finished importing.

idstringformat: "uuid"
stateenum
completed means every entry succeeded. failed may contain successful entries alongside failures.
Allowed values:
totalinteger1-25
completedinteger>=0
failedinteger>=0
resultslist of objects

Finished entries only; pending entries have no result yet.

statusUrlstring
Relative URL to poll with the same API credential that submitted the batch.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error