Skip to main content

Update Draft (overrides, images, structure)

PUT 
/api/v2/listing-drafts/:draft

Update a draft — saves field_overrides, image_urls, and structural changes (sales_channel_category_id, sales_channel_product_template_id, sales_channel_listing_profile_id), then re-resolves and re-validates. The draft transitions to ready when no validation errors remain.

Required scope: products:write

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

field_overrides values come in two shapes:

  • Literal value (string / number / bool / array for multiselect) — used verbatim, provenance override.
  • Mapped source — an object {"source_type": ..., "source_value": ...} that re-resolves from product data on every validate/publish. source_type must be one of product_field (whitelisted product columns — see GET /api/v2/listing-drafts/mappable-product-fields), product_attribute (an Attribute id), static (literal string), or expression (mustache tokens, e.g. {{product.sku}} - {{product.name}}). A mapped override that resolves to null stays null (no fall-through to template/mapping values) so required-field validation can flag it.

Passing an invalid source_type, or a source_value that is not a scalar, returns 422.

Fields:

  • field_overrides (nullable, object) — map of field name to literal value or mapped source (see above).
  • sales_channel_category_id (nullable, integer)
  • sales_channel_product_template_id (nullable, integer)
  • sales_channel_listing_profile_id (nullable, integer)
  • image_urls (nullable, array of strings)

Authentication: Requires Bearer token.

variant_context — describes whether this draft targets a single VARIANT of a matrix family rather than the family itself. When is_variant_child is true, parent_sku / parent_name identify the family and sibling_count is how many variants it has. Publishing a single child is permitted, but it creates a standalone channel item with no variant group — publish the parent to list the whole family as one grouped listing. null when the draft has no product.

Each field's schema reports the channel's constraints. cardinality is the MAXIMUM number of values the field accepts (0 = unbounded) and min_cardinality is the MINIMUM (0 = none). A channel can require several entries on one field - Walmart's Cloth Baby Diapers category asks for at least 4 Key Features and 4 additional images - and rejects the item after accepting the submission, so supply at least min_cardinality values before publishing.

category_provenance (optional: override | type_map | manual) records where a changed category came from. Omitting field_overrides leaves the draft's saved overrides untouched; send an empty array to clear them.

Request​

Responses​

OK