PartnerOrderData

Part of the response of 7 operations and the payload of order.updated.

Type: object

Fields

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

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

created_at string required

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

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

currency string required

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

Example CAD

customer OrderWebhookCustomer required

The buyer details saved when the order was created.

Show child fieldsHide child fields

customer.name string required

Example Alex Morgan

customer.email string required

The contact email address.

Example alex.morgan@example.test

customer.shipping_address OrderWebhookShippingAddress required

The shipping address saved when the order was created.

Show child fieldsHide child fields

customer.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

customer.shipping_address.line2 string or null required

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

Example Unit 4

customer.shipping_address.city string required

The city in the shipping address.

Example Toronto

customer.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

customer.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

customer.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

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

ship_to.name string required

The recipient name to print on the label.

Example Alex Morgan

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

ship_to.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

ship_to.shipping_address.line2 string or null required

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

Example Unit 4

ship_to.shipping_address.city string required

The city in the shipping address.

Example Toronto

ship_to.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

ship_to.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

ship_to.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

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

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

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

address_verification.suggested_address.line1 string required

The street address.

address_verification.suggested_address.line2 string or null required

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

address_verification.suggested_address.city string required

The city in the shipping address.

address_verification.suggested_address.province string required

The Canadian province or territory in the delivery address.

address_verification.suggested_address.postal_code string required

The Canadian postal code in the delivery address.

address_verification.suggested_address.country string required

ISO 3166-1 alpha-2 country code.

lines array of object required

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

Show child fieldsHide child fields

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

lines[].sku_id integer required

Canonical TCGplayer SKU id (STABLE).

Example 14602

lines[].product_id integer required

Canonical TCGplayer product id (STABLE).

Example 86

lines[].quantity integer required

The number of units.

Example 1

lines[].unit_price integer required

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

Example 2499

lines[].name string or null required

Descriptive snapshot, frozen at order time (STABLE).

Example Abyssal Nightstalker

lines[].set string or null required

The card set or expansion.

Example Portal Second Age

lines[].condition string or null required

The normalized condition assigned to the card.

Example NM

lines[].external_ref string or null required

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

Example platform-listing-1042

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

lines[].language string or null

The language of the card printing.

Example English

lines[].finish string or null

The physical finish or foil treatment of the card.

Example Non-Foil

lines[].disclosures object

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

Show child fieldsHide child fields

lines[].disclosures.image_source string required

Who supplied the product image shown to the buyer.

Constraints: allowed values: catalog

lines[].disclosures.condition_source string required

Who assigned the displayed card condition.

Constraints: allowed values: seller_declared

lines[].disclosures.authenticity_source string required

Who supplied the authenticity determination.

Constraints: allowed values: seller_attestation

lines[].disclosures.snapcaster_inspected boolean required

Whether Snapcaster physically inspected the card.

Constraints: allowed values: false

lines[].disclosures.snapcaster_graded boolean required

Whether Snapcaster assigned the displayed grade.

Constraints: allowed values: false

lines[].disclosures.snapcaster_authenticated boolean required

Whether Snapcaster authenticated the card.

Constraints: allowed values: false

lines[].disclosures.grading_standard string required

The grading standard used for the declared grade.

lines[].disclosures.declared_grade string or null required

The grade declared for the card under the named standard.

lines[].disclosures.buyer_protection string required

The buyer-protection coverage attached to this offering.

lines[].fulfillment_obligation object

The exact item characteristics the seller must fulfill.

Show child fieldsHide child fields

lines[].fulfillment_obligation.sku string required

The SKU that identifies the card variant.

Constraints: allowed values: exact

lines[].fulfillment_obligation.printing string required

The card printing the seller must supply.

Constraints: allowed values: exact

lines[].fulfillment_obligation.language string required

The language of the card printing.

Constraints: allowed values: exact

lines[].fulfillment_obligation.finish string required

The physical finish or foil treatment of the card.

Constraints: allowed values: exact

lines[].fulfillment_obligation.condition string required

The normalized condition assigned to the card.

Constraints: allowed values: declared-or-better

lines[].cancelled_quantity integer required

Constraints: minimum: 0 Example 0

lines[].refunded_quantity integer required

Constraints: minimum: 0 Example 0

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

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

lines[].substitution.request_id integer required

The fulfillment report that last rewrote this line.

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

lines[].substitution.original.sku_id integer required

See Canonical catalog in Core concepts.

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

See Canonical catalog in Core concepts.

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

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

The card set or expansion.

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

The normalized condition assigned to the card.

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

The language of the card printing.

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

The physical finish or foil treatment of the card.

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

The rarity assigned to the card printing.

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

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

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

totals.subtotal integer required

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

Example 2499

totals.shipping integer required

The shipping charge or delivery details for the order.

Example 599

totals.tax integer required

The tax total or breakdown applied to the order.

Example 403

totals.grand_total integer required

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

Example 3501

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

tax.lines array of object required

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

Show child fieldsHide child fields

tax.lines[].label string required

Example HST

tax.lines[].rate number required

The decimal tax rate applied to the taxable amount.

Example 0.13

tax.lines[].amount integer required

The monetary amount in minor currency units.

Example 403

shipping object

The shipping charge or delivery details for the order.

Show child fieldsHide child fields

shipping.method string required

Example Tracked parcel

shipping.cost integer required

The shipping cost in minor currency units.

Example 599

shipping.is_tracked boolean or null required

Example true

buyer_notes string

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

Example Please protect the card with a top loader.

status string required

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

fulfillment OrderFulfillment

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

Show child fieldsHide child fields

fulfillment.tracking_company string required

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

fulfillment.tracking_number string required

Carrier tracking number (STABLE).

fulfillment.tracking_url string or null required

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

updated_at string required

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

dispatch object required

Show child fieldsHide child fields

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

dispatch.dispatched_at string or null required

Constraints: format: date-time Example null

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

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

cancellations array of object required

Show child fieldsHide child fields

cancellations[].id string required

cancellations[].created_at string required

Constraints: format: date-time

cancellations[].lines array of object required

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

Show child fieldsHide child fields

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.

cancellations[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

cancellations[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

cancellations[].payment_refund object or null required

Show child fieldsHide child fields

cancellations[].payment_refund.amount integer required

The monetary amount in minor currency units.

cancellations[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

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

refunds array of object required

Show child fieldsHide child fields

refunds[].id string required

refunds[].created_at string required

Constraints: format: date-time

refunds[].lines array of object required

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

Show child fieldsHide child fields

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.

refunds[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

refunds[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

refunds[].payment_refund object or null required

Show child fieldsHide child fields

refunds[].payment_refund.amount integer required

The monetary amount in minor currency units.

refunds[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

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

refunds[].restock boolean required

Whether fulfilled units return to on-hand inventory.

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

substitutions[].id string required

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

substitutions[].request_id integer required

The fulfillment report the buyer accepted.

substitutions[].created_at string required

When the buyer accepted the report.

Constraints: format: date-time

substitutions[].lines array of object required

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

Show child fieldsHide child fields

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

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

substitutions[].lines[].original_sku_id integer required

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

substitutions[].lines[].quantity integer required

The number of units.

Constraints: exclusive minimum: 0

substitutions[].lines[].action string required

How to resolve this issue.

Constraints: allowed values: remove, substitute

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

The SKU that ships instead. Null on a removal.

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

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

substitutions[].payment_refund.amount integer required

The monetary amount in minor currency units.

substitutions[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

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

pending_cancellation_requests array of object required

Show child fieldsHide child fields

pending_cancellation_requests[].id string required

pending_cancellation_requests[].created_at string required

Constraints: format: date-time

pending_cancellation_requests[].reason string or null required

pending_cancellation_requests[].lines array of object or null required

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

Show child fieldsHide child fields

pending_cancellation_requests[].lines[].line_ref string required

pending_cancellation_requests[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

pending_cancellation_requests[].lines[].quantity integer

The number of units.

Constraints: exclusive minimum: 0

Used by

• GET /orders - Poll orders (response)
• GET /orders/{orderId} - Get one order (response)
• PATCH /orders/{orderId}/fulfillment - Update fulfillment (response)
• POST /orders/{orderId}/cancel - Cancel an order (response)
• POST /orders/{orderId}/refunds - Create a refund (response)
• POST /orders/{orderId}/corrections - Correct the ship-to address (response)
• POST /orders/{orderId}/address-verification/retry - Retry address verification (response)
• order.updated - Order updated (payload)