Skip to main content

Get Publish-Readiness Snapshot

GET 
/api/v2/products/:product/publish-readiness

Per-product, multi-channel publish readiness snapshot. Returns one entry per publish-capable, connected sales channel, grouped by bucket (live / ready / ready_to_list / warn / idle / publishing / scheduled / draft) so the publish dialog can render confidence groups without orchestrating N parallel calls.

Required scope: products:read

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

Read-only: does NOT speculatively create drafts. Channels with no draft and no live listing land in idle and surface recommended next actions (pick a template, create one, etc.).

Bucket resolution:

  • live — a non-archived ProductListing exists for this product on the channel
  • ready — open draft in state ready
  • scheduled — open draft in state scheduled
  • publishing — open draft in state publishing or validating
  • warn — open draft in state error, OR draft with validation errors
  • draft — open draft in state draft with no validation errors
  • removed — the listing was live and the channel no longer hosts it
  • idle — no open draft and no live listing

Authentication: Requires Bearer token.

quantity_to_push (int|null, per channel entry) — the stock a publish to this channel would seed right now, computed through the same SalesChannelInventoryCalculator rules the standing inventory sync uses (max/min/buffer, locations, bundles). null when quantity seeding is gated off (listing-publishing push_quantity_on_publish setting disabled, SKU.io not master of stock for the instance, no inventory rules configured) or the bucket cannot publish (live / publishing).

quantity_variant_count (int|null, per channel entry) — how many variants the quantity_to_push figure is spread across. Non-null only for a matrix parent, whose own stock is always zero because every unit sits on a child: the figure is the sum across its variants, each of which is seeded with its own quantity when the family publishes. Null for a standalone product, whose figure is its own.

existing_listing (object|null, per channel entry) — the channel-side listing when one exists, else null. Fields:

  • remote_status — the last reconciled channel-side state: live, pending (accepted, still being ingested by the channel), rejected (the channel accepted the submission then refused to publish it, so it never went live), missing (was live, no longer hosted), archived (hosted but hidden from shoppers), or unknown.
  • remote_status_checked_at — when that state was last confirmed with the channel.
  • remote_status_reason (string|null) — the channel's own explanation when it refused the listing, shown verbatim so it names what to fix. For example, a Walmart item withheld for a missing primary image reports "This item is missing a primary image. Add a 'Main Image URL' and resubmit the item." null when the channel gave no reason. A rejected listing stays rejected until the underlying problem is corrected and it is published again — resubmitting unchanged fails identically.

draft.channel_errors — what the SALES CHANNEL said when it refused the item, as distinct from validation_errors, which is what this system's own validation found before anything was sent. Each entry carries the channel's code, its message, and the field it names where one is given; channel_errors_count is the same list's length.

The two are different problems and want different handling: outstanding validation_errors mean the item is not ready to send, while channel_errors mean it was sent and came back rejected — republishing it unchanged will fail the same way.

Request​

Responses​

OK