Poll orders

200

A page of orders.

Response body: OrderPollPageResponse

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true Example true

data object required

The operation or event payload.

Show child fieldsHide child fields

data.items PartnerOrderData[] required

Complete current order states, including cancellation and refund quantities.

Show child fieldsHide child fields

data.items[].order_id string required

The Snapcaster order id. Use this stable id to reconcile events and poll results for the same seller order (STABLE).

Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

data.items[].seller_id integer required

The seller that owns the API key. Use this id to route the event to the right store (STABLE).

Example 42

data.items[].created_at string required

ISO-8601 UTC instant the order was created (STABLE).

Example 2026-09-04T18:42:17.000Z

data.items[].currency string required

ISO 4217 currency code, e.g. CAD (STABLE).

Example CAD

data.items[].customer OrderWebhookCustomer required

The buyer details saved when the order was created.

Show child fieldsHide child fields

data.items[].customer.name string required

Example Alex Morgan

data.items[].customer.email string required

The contact email address.

Example alex.morgan@example.test

data.items[].customer.shipping_address OrderWebhookShippingAddress required

The shipping address saved when the order was created.

Show child fieldsHide child fields

data.items[].customer.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

data.items[].customer.shipping_address.line2 string or null required

The unit, suite, or second address line, if supplied.

Example Unit 4

data.items[].customer.shipping_address.city string required

The city in the shipping address.

Example Toronto

data.items[].customer.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

data.items[].customer.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

data.items[].customer.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.items[].ship_to OrderShipTo required

Where the order ships: the newest seller address correction if one exists, otherwise the customer snapshot. Always present. Print from this block, not from customer. On order.created it always equals the snapshot; a later correction reaches you through GET /orders (the order reappears with a new updated_at), never by changing that event’s bytes (STABLE).

Show child fieldsHide child fields

data.items[].ship_to.name string required

The recipient name to print on the label.

Example Alex Morgan

data.items[].ship_to.shipping_address OrderWebhookShippingAddress or null required

The six-field §6.1 address to print on the label. null only for an order minted without a shipping address (an operator-seeded or legacy row), which checkout never produces.

Show child fieldsHide child fields

data.items[].ship_to.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

data.items[].ship_to.shipping_address.line2 string or null required

The unit, suite, or second address line, if supplied.

Example Unit 4

data.items[].ship_to.shipping_address.city string required

The city in the shipping address.

Example Toronto

data.items[].ship_to.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

data.items[].ship_to.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

data.items[].ship_to.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.items[].address_verification OrderAddressVerification required

The post-order address verification verdict on the customer snapshot, and the suggested address when one differs from it. Always present; pending until a verdict lands. On order.created it is always pending: the check runs after the order is placed, and a retried event stays byte-identical. A landed verdict reaches you through GET /orders (the order reappears with a new updated_at) (STABLE).

Show child fieldsHide child fields

data.items[].address_verification.status string required

The verification status of the customer shipping address. pending until a verdict lands (a fresh order always reads pending); verified / verified_unit mean deliverable; missing_unit / unit_unconfirmed / not_found are address problems worth a look before shipping; failed means the check itself could not run and says nothing about the address. Closed vocabulary, extended additively (STABLE).

Constraints: allowed values: pending, verified, verified_unit, missing_unit, unit_unconfirmed, not_found, failed Example pending

data.items[].address_verification.suggested_address OrderWebhookShippingAddress or null required

The standardized address the verification suggests, present only when a verdict landed with a suggestion that differs from the customer snapshot; null otherwise. Advisory: the seller decides where to ship, and that decision is ship_to (STABLE).

Show child fieldsHide child fields

data.items[].address_verification.suggested_address.line1 string required

The street address.

data.items[].address_verification.suggested_address.line2 string or null required

The unit, suite, or second address line, if supplied.

data.items[].address_verification.suggested_address.city string required

The city in the shipping address.

data.items[].address_verification.suggested_address.province string required

The Canadian province or territory in the delivery address.

data.items[].address_verification.suggested_address.postal_code string required

The Canadian postal code in the delivery address.

data.items[].address_verification.suggested_address.country string required

ISO 3166-1 alpha-2 country code.

data.items[].lines array of object required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].lines[].line_ref string required

The purchase-line reference, for example oln_1f0c…. It identifies WHICH PURCHASE this line is, where sku_id identifies which card. One order can hold two lines of the same sku_id bought at different times and prices, so key your fulfillment records on this field. It is also what you send back in lines[].lineRef when you cancel or refund a line.

Example oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241

data.items[].lines[].sku_id integer required

Canonical TCGplayer SKU id (STABLE).

Example 14602

data.items[].lines[].product_id integer required

Canonical TCGplayer product id (STABLE).

Example 86

data.items[].lines[].quantity integer required

The number of units.

Example 1

data.items[].lines[].unit_price integer required

Integer minor units (cents) in the order currency (STABLE).

Example 2499

data.items[].lines[].name string or null required

Descriptive snapshot, frozen at order time (STABLE).

Example Abyssal Nightstalker

data.items[].lines[].set string or null required

The card set or expansion.

Example Portal Second Age

data.items[].lines[].condition string or null required

The normalized condition assigned to the card.

Example NM

data.items[].lines[].external_ref string or null required

The seller's listing reference, returned unchanged; null if none was supplied (STABLE).

Example platform-listing-1042

data.items[].lines[].collector_number string or null required

The card's catalog collector number, saved when the order was created, for example 161/302. Null if the catalog had no number or the order predates this field. An additive field on the STABLE line.

Example null

data.items[].lines[].language string or null

The language of the card printing.

Example English

data.items[].lines[].finish string or null

The physical finish or foil treatment of the card.

Example Non-Foil

data.items[].lines[].disclosures object

Provenance, grading, and authenticity statements shown to the buyer.

Show child fieldsHide child fields

data.items[].lines[].disclosures.image_source string required

Who supplied the product image shown to the buyer.

Constraints: allowed values: catalog

data.items[].lines[].disclosures.condition_source string required

Who assigned the displayed card condition.

Constraints: allowed values: seller_declared

data.items[].lines[].disclosures.authenticity_source string required

Who supplied the authenticity determination.

Constraints: allowed values: seller_attestation

data.items[].lines[].disclosures.snapcaster_inspected boolean required

Whether Snapcaster physically inspected the card.

Constraints: allowed values: false

data.items[].lines[].disclosures.snapcaster_graded boolean required

Whether Snapcaster assigned the displayed grade.

Constraints: allowed values: false

data.items[].lines[].disclosures.snapcaster_authenticated boolean required

Whether Snapcaster authenticated the card.

Constraints: allowed values: false

data.items[].lines[].disclosures.grading_standard string required

The grading standard used for the declared grade.

data.items[].lines[].disclosures.declared_grade string or null required

The grade declared for the card under the named standard.

data.items[].lines[].disclosures.buyer_protection string required

The buyer-protection coverage attached to this offering.

data.items[].lines[].fulfillment_obligation object

The exact item characteristics the seller must fulfill.

Show child fieldsHide child fields

data.items[].lines[].fulfillment_obligation.sku string required

The SKU that identifies the card variant.

Constraints: allowed values: exact

data.items[].lines[].fulfillment_obligation.printing string required

The card printing the seller must supply.

Constraints: allowed values: exact

data.items[].lines[].fulfillment_obligation.language string required

The language of the card printing.

Constraints: allowed values: exact

data.items[].lines[].fulfillment_obligation.finish string required

The physical finish or foil treatment of the card.

Constraints: allowed values: exact

data.items[].lines[].fulfillment_obligation.condition string required

The normalized condition assigned to the card.

Constraints: allowed values: declared-or-better

data.items[].lines[].cancelled_quantity integer required

Constraints: minimum: 0 Example 0

data.items[].lines[].refunded_quantity integer required

Constraints: minimum: 0 Example 0

data.items[].lines[].substitution_credit_cents integer required

The credit per unit every accepted substitution of this line returned to the buyer, summed. unit_price never changes, so the line is worth unit_price - substitution_credit_cents per unit. 0 on a line never substituted.

Constraints: minimum: 0 Example 0

data.items[].lines[].substitution object or null required

Present once a substitution has rewritten this line: sku_id and the card details now name the card that ships. Null on a line that ships as sold.

Show child fieldsHide child fields

data.items[].lines[].substitution.request_id integer required

The fulfillment report that last rewrote this line.

data.items[].lines[].substitution.original object or null required

The card the line carried before that report rewrote it, as the report recorded it. A fact the report did not record is null.

Show child fieldsHide child fields

data.items[].lines[].substitution.original.sku_id integer required

See Canonical catalog in Core concepts.

data.items[].lines[].substitution.original.product_id integer or null required

See Canonical catalog in Core concepts.

data.items[].lines[].substitution.original.name string or null required

data.items[].lines[].substitution.original.set string or null required

The card set or expansion.

data.items[].lines[].substitution.original.condition string or null required

The normalized condition assigned to the card.

data.items[].lines[].substitution.original.language string or null required

The language of the card printing.

data.items[].lines[].substitution.original.finish string or null required

The physical finish or foil treatment of the card.

data.items[].lines[].substitution.original.rarity string or null required

The rarity assigned to the card printing.

data.items[].lines[].substitution.original.collector_number string or null required

data.items[].lines[].reported_line_ref string or null required

The line_ref of the line a substitution split this line from. Always null today: substitutions replace whole lines.

Example null

data.items[].totals object

Order totals in integer cents in the order currency. When present, includes all four values: subtotal, shipping, tax, and grand_total, where grand_total = subtotal + shipping + tax (STABLE).

Show child fieldsHide child fields

data.items[].totals.subtotal integer required

The line-item total before shipping and tax, in minor currency units.

Example 2499

data.items[].totals.shipping integer required

The shipping charge or delivery details for the order.

Example 599

data.items[].totals.tax integer required

The tax total or breakdown applied to the order.

Example 403

data.items[].totals.grand_total integer required

The complete order total including shipping and tax, in minor currency units.

Example 3501

data.items[].tax object

One {label, rate, amount} line per applied tax. This block is absent if and only if totals.tax is zero (STABLE).

Show child fieldsHide child fields

data.items[].tax.lines array of object required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].tax.lines[].label string required

Example HST

data.items[].tax.lines[].rate number required

The decimal tax rate applied to the taxable amount.

Example 0.13

data.items[].tax.lines[].amount integer required

The monetary amount in minor currency units.

Example 403

data.items[].shipping object

The shipping charge or delivery details for the order.

Show child fieldsHide child fields

data.items[].shipping.method string required

Example Tracked parcel

data.items[].shipping.cost integer required

The shipping cost in minor currency units.

Example 599

data.items[].shipping.is_tracked boolean or null required

Example true

data.items[].buyer_notes string

Optional free-text buyer note; absent when the buyer left none (STABLE).

Example Please protect the card with a top loader.

data.items[].status string required

Constraints: allowed values: created, accepted, shipped, delivered, cancelled, refunded Example created

data.items[].fulfillment OrderFulfillment

Tracking details, present once tracking has been added during fulfillment (STABLE).

Show child fieldsHide child fields

data.items[].fulfillment.tracking_company string required

Carrier/company name, as the fulfiller entered it (STABLE).

data.items[].fulfillment.tracking_number string required

Carrier tracking number (STABLE).

data.items[].fulfillment.tracking_url string or null required

Tracking link; null if the fulfiller supplied none (STABLE).

data.items[].updated_at string required

Constraints: format: date-time Example 2026-09-04T18:42:17.000Z

data.items[].dispatch object required

Show child fieldsHide child fields

data.items[].dispatch.deadline_at string or null required

The ship-by deadline: the end of the third Toronto business day after the order was placed, fixed when the order is created. Null on an order Snapcaster created without one (STABLE).

Constraints: format: date-time Example 2026-09-08T23:59:59.000Z

data.items[].dispatch.dispatched_at string or null required

Constraints: format: date-time Example null

data.items[].dispatch.overdue_at string or null required

When Snapcaster marked the order overdue because it had not shipped by deadline_at, which also sends order.dispatch_overdue. Null until then (STABLE).

Constraints: format: date-time Example null

data.items[].dispatch.payout_paused boolean required

True while the seller payout for this order is paused. An overdue dispatch pauses it, and so can a Snapcaster review of the order; shipping does not lift it, only Snapcaster releasing the payout does (STABLE).

Example false

data.items[].cancellations array of object required

Show child fieldsHide child fields

data.items[].cancellations[].id string required

data.items[].cancellations[].created_at string required

Constraints: format: date-time

data.items[].cancellations[].lines array of object required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].cancellations[].lines[].line_ref string or null required

The purchase-line reference of the line this cancellation or refund terminated, the same line_ref the order line and the matching order.cancelled or order.refunded line carry. Reconcile on this field: an order can hold two lines of one sku_id. Null only on a cancellation recorded before Snapcaster kept an order event log, when its sku_id names more than one line on the order or a substitution has rewritten a line on the order.

data.items[].cancellations[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

data.items[].cancellations[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

data.items[].cancellations[].payment_refund object or null required

Show child fieldsHide child fields

data.items[].cancellations[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.items[].cancellations[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.items[].cancellations[].payment_refund.status string required

failed if any payment the refund came back on refused it, succeeded once every one settled, otherwise pending. It can change in either direction, after a bank return or a retry; each change sends order.updated with reason: payment_refund_updated.

Constraints: allowed values: pending, succeeded, failed

data.items[].refunds array of object required

Show child fieldsHide child fields

data.items[].refunds[].id string required

data.items[].refunds[].created_at string required

Constraints: format: date-time

data.items[].refunds[].lines array of object required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].refunds[].lines[].line_ref string or null required

The purchase-line reference of the line this cancellation or refund terminated, the same line_ref the order line and the matching order.cancelled or order.refunded line carry. Reconcile on this field: an order can hold two lines of one sku_id. Null only on a cancellation recorded before Snapcaster kept an order event log, when its sku_id names more than one line on the order or a substitution has rewritten a line on the order.

data.items[].refunds[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

data.items[].refunds[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

data.items[].refunds[].payment_refund object or null required

Show child fieldsHide child fields

data.items[].refunds[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.items[].refunds[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.items[].refunds[].payment_refund.status string required

failed if any payment the refund came back on refused it, succeeded once every one settled, otherwise pending. It can change in either direction, after a bank return or a retry; each change sends order.updated with reason: payment_refund_updated.

Constraints: allowed values: pending, succeeded, failed

data.items[].refunds[].restock boolean required

Whether fulfilled units return to on-hand inventory.

data.items[].substitutions array of object required

Every accepted fulfillment report that substituted at least one line, oldest first. A report that only removed lines is a cancellation and appears in cancellations. Empty when there is none.

Show child fieldsHide child fields

data.items[].substitutions[].id string required

The substitution id, also the adjustmentId Snapcaster stamps on the payment refund it issued.

data.items[].substitutions[].request_id integer required

The fulfillment report the buyer accepted.

data.items[].substitutions[].created_at string required

When the buyer accepted the report.

Constraints: format: date-time

data.items[].substitutions[].lines array of object required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].substitutions[].lines[].line_ref string or null required

The purchase-line reference the report named. Null only when no retained record names the purchase.

data.items[].substitutions[].lines[].original_sku_id integer required

The SKU the line carried when the seller filed the report.

data.items[].substitutions[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

data.items[].substitutions[].lines[].action string required

How to resolve this issue.

Constraints: allowed values: remove, substitute

data.items[].substitutions[].lines[].substitute_sku_id integer or null required

The SKU that ships instead. Null on a removal.

data.items[].substitutions[].lines[].credit_cents integer or null required

The credit per unit this substitution returned to the buyer. Null on a removal, which returns what the units were worth.

Constraints: minimum: 0

data.items[].substitutions[].payment_refund object or null required

The money the substitution returned to the buyer, across every payment it came back on: every credit plus any removed units, with their share of the purchase fee and tax. Null when it moved no money.

Show child fieldsHide child fields

data.items[].substitutions[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.items[].substitutions[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.items[].substitutions[].payment_refund.status string required

failed if any payment the refund came back on refused it, succeeded once every one settled, otherwise pending. It can change in either direction, after a bank return or a retry; each change sends order.updated with reason: payment_refund_updated.

Constraints: allowed values: pending, succeeded, failed

data.items[].pending_cancellation_requests array of object required

Show child fieldsHide child fields

data.items[].pending_cancellation_requests[].id string required

data.items[].pending_cancellation_requests[].created_at string required

Constraints: format: date-time

data.items[].pending_cancellation_requests[].reason string or null required

data.items[].pending_cancellation_requests[].lines array of object or null required

The line items in this request, response, or event.

Show child fieldsHide child fields

data.items[].pending_cancellation_requests[].lines[].line_ref string required

data.items[].pending_cancellation_requests[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

data.items[].pending_cancellation_requests[].lines[].quantity integer

The number of units.

Constraints: exclusive minimum: 0

data.nextCursor string or null required

Continue with cursor until this is null.

Example null

data.syncToken string

Present on the final page. Save only after processing every page; use as syncToken for the next pass.

Example opaque-sync-token