Upload items to a dataset

Queues up to 5,000 products for processing in one request. Nothing is searchable yet when this call returns: each product becomes a pending queue entry, and a background worker turns it into a DatasetItem — downloading and storing its images, extracting style metadata and computing embeddings. Track progress with the queue endpoints; the itemId of a queue entry is the itemId of the item it produces.

disableGenerativeAssets is accepted for compatibility but ignored: generative thumbnails are disabled platform-wide and every entry is stored with the value true.

Validation

Validation is all-or-nothing. Every product is checked before any is queued; if one fails, the whole request is rejected and nothing is written. Failures come back in details as { index, path, message } where index is the product's position in items (or -1 for request-wide SKU problems) and path is the offending field. The per-field messages are:

• Product must be an object.
• Expected string, got <type> — one of name, handle, description, publishedAt, createdAt, updatedAt, productType, sku is not a string
• Price must be a non-negative number.
• SKU must not be empty. — sku is blank or only whitespace
• Unparseable date: <value> — publishedAt, createdAt or updatedAt cannot be parsed by Date
• Expected an array. — tags, images, options or variants is not an array
• Expected <type>, got <type> — an element of those arrays has the wrong type (tags must hold strings; the others objects)
• Expected string. — a variant's sku, name, createdAt, updatedAt or productId is not a string
• Price must be non-negative number. — a variant's price
• Expected boolean. — a variant's available
• Expected one of mens, womens, unisex, or null. — gender is present and not one of those

Dates are normalised to ISO 8601 UTC before they are stored. An empty publishedAt is accepted and means the product is unpublished. Fields outside the documented shape are dropped.

A few rules are enforced only by the database when the batch is written, and break the whole request with the shared 500 Internal server error. (nothing is queued): name and handle must be non-empty; each variant's name and productId must be non-empty; every images entry needs a src; tags and option values must not contain empty strings. A variants value that is neither an array nor omitted, or a null element inside variants, also returns the shared 500 Internal server error.

Re-uploading a product

SKUs are matched ignoring case and surrounding whitespace, the same way a data source sync matches them. A SKU must appear only once in the request. When it already has a queue entry in the dataset (in any status except archived), the upload updates that entry instead of creating a second one:

• updatedAt differs from the stored product → the entry is re-queued. If the image URLs changed it goes through full processing again (pending); otherwise only name, description, price and sizes are refreshed (partial_update).
• The entry is failed → it is re-queued for full processing.
• Otherwise nothing is written; the product is counted as unchanged.

A SKU whose only entry is archived brings that entry back, with the same itemId, and is counted as revived. If it was fully processed and its image URLs, name and product type are unchanged, it returns through partial_update; otherwise it is processed again (pending).

This makes the endpoint safe to retry, and usable for price and stock refreshes as long as updatedAt moves with the change.