Skip to main content

Create Draft

POST 
/api/v2/listing-drafts

Create a listing draft.

Required scope: products:write

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

Fields:

  • purpose (required, create | update) — create builds a new-listing draft; update seeds a draft from an existing live listing.
  • product_id (required if purpose=create, integer) — product to list.
  • sales_channel_id (required if purpose=create, integer) — target channel.
  • sales_channel_category_id (nullable, integer) — channel category driving the field schema. Omit it to have the product's channel category resolved automatically: the product's own override on this channel, else the category its product type is mapped to on the channel (that category's default template is used unless sales_channel_product_template_id is given). A draft that still has no category records a missing_category validation error and stays in draft state — it can never reach ready until a category is set.
  • category_provenance (nullable, override | type_map | manual) — where a supplied sales_channel_category_id came from, so the draft records it; pass the value returned by Resolve Draft Categories or List Product Channel Categories. A category supplied without it is recorded as manual; a category resolved automatically records its own provenance. Echoed as category_provenance in the response (null when the draft has no category).
  • sales_channel_product_template_id (nullable, integer) — template pre-mapping category fields. Optional: a draft is fully publishable without one (fill fields via overrides).
  • sales_channel_listing_profile_id (nullable, integer) — channel listing profile.
  • product_listing_id (required if purpose=update, integer) — live listing to seed from.

The draft is resolved + validated on creation; the response includes fields[] (schema + resolved value + provenance + raw override), resolved_values and validation_errors.

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.

Refusals (422): the draft is refused, with the reason in message, when the product is outside the channel's catalog, or when the account was connected through the Shopify App Store and the channel is a marketplace (Amazon, eBay, Walmart, Temu, TikTok Shop, Faire) or the product is already listed on a different Shopify store. Update drafts (purpose: update) follow the same rules.

Request​

Responses​

Created