Skip to main content

Get Draft

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

Show a draft with the full per-field payload.

Required scope: products:read

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

Each fields[] row merges the cached category schema with the draft's resolved value:

  • value — resolved value after the precedence chain (override > template > channel mapping > integration mapping > blank)
  • provenance — where the value came from (override, template, channel_mapping, integration_mapping, blank)
  • has_override — whether the draft overrides this field
  • override — the raw override: a literal value, or a mapped source object {source_type, source_value}
  • errors — validation/channel errors scoped to this field

category_provenance says where the draft's category came from: override (the product's own override on the channel), type_map (its product type's channel category map) or manual (chosen when the draft was created); null when the draft has no category.

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.

fields[].variant_values — a matrix product publishes as one item per variant, each resolving its own data, so a single value cannot describe what will be sent. This array carries the field's value on every variant, in child order: sku, value, and the provenance it resolved from. Empty for a product with no variants, where value alone is the whole answer.

Use it to see which variants are missing a required field: in the example above the listing is blocked because one of the two variants has no image, and variant_values names which one.

fields[].source_type / source_value identify what the value resolved from (a product column, a product attribute, a fixed value), so a client can show the mapping rather than just the result.

Request​

Responses​

OK