Order updated

Sent when an order changes after creation: a post-order address verification verdict lands on the customer address (reason: address_verified), the seller records an address correction (reason: address_corrected), a line is substituted for another version of the same card and the buyer accepts it (reason: line_substituted), or the buyer pays for additional cards on the order (reason: items_added, not yet sent because order additions are not yet available), or the payment_refund.status of a cancellation, refund or substitution changes after its first event, in either direction (reason: payment_refund_updated). Lifecycle transitions never send it: a cancellation or a refund sends its own event, and the forward transitions (accepted, shipped, delivered) send no webhook. Reuses the order.created envelope, signing, and delivery semantics (see https://developers.snapcaster.ca/guide/webhook-signing and https://developers.snapcaster.ca/guide/path-b#delivery-semantics). Routed only to order-family subscriptions (orders / both); the inventory family never receives it. data is the full current order body - the same shape as GET /orders/{orderId} - as it stood when the change was recorded, plus reason. Print the label from ship_to, and pick from lines: on line_substituted a line names a different card than the one order.created carried, at the same unit_price and quantity; once order additions are available, items_added lines will hold entries that were not in order.created at all. Reconcile lines by line_ref, never by sku_id: one order can hold two lines of one card. order.created is never rewritten - a retry of it still carries only the cards bought at checkout. The body is frozen when the event is generated, so a retry is byte-identical even if a later correction landed in between, except that a corrected guest email reaches every later delivery in customer.email; each emission has its own event_id. No ordering guarantee: compare the envelope created_at, or re-read GET /orders/{orderId} for the latest state.

Signature headers

Snapcaster sends a POST to your webhook endpoint with these headers. Webhook signing shows how to verify them.

X-Snapcaster-Timestamp string required

Unix seconds when the request was signed; reject if outside a ±5 minute window.

X-Snapcaster-Signature string required

sha256= + lowercase hex of HMAC_SHA256(signingSecret, timestamp ‖ raw request body).

Delivery payload

The signed order.updated event.

Payload type: OrderUpdatedEvent

Envelope fields

event_id string required

Globally unique, stable across retries. Each emission is its own event with its own id: two corrections are two events (STABLE).

Example evt_sandbox_01K4A9M2R7T3X9B5D1F6H8K0NQ

type string required

Event discriminator (STABLE).

Constraints: allowed values: order.updated Example order.updated

created_at string required

ISO-8601 UTC instant the change was recorded - the verdict or the correction, not the order’s creation (STABLE).

Example 2026-09-05T14:20:00.000Z

data OrderUpdatedData required

The operation or event payload.

api_version string required

The dated API version used for this payload, frozen when Snapcaster queued the delivery. Changing the platform pin does not change queued events or retries; they keep the same version. See https://developers.snapcaster.ca/guide/api-versioning (STABLE).

Constraints: allowed values: 2026-10 Example 2026-10

Payload fields

data.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.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.created_at string required

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

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

data.currency string required

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

Example CAD

data.customer OrderWebhookCustomer required

The buyer details saved when the order was created.

Show child fieldsHide child fields

data.customer.name string required

Example Alex Morgan

data.customer.email string required

The contact email address.

Example alex.morgan@example.test

data.customer.shipping_address OrderWebhookShippingAddress required

The shipping address saved when the order was created.

Show child fieldsHide child fields

data.customer.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

data.customer.shipping_address.line2 string or null required

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

Example Unit 4

data.customer.shipping_address.city string required

The city in the shipping address.

Example Toronto

data.customer.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

data.customer.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

data.customer.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.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.ship_to.name string required

The recipient name to print on the label.

Example Alex Morgan

data.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.ship_to.shipping_address.line1 string required

The street address.

Example 123 Sandbox Avenue

data.ship_to.shipping_address.line2 string or null required

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

Example Unit 4B

data.ship_to.shipping_address.city string required

The city in the shipping address.

Example Toronto

data.ship_to.shipping_address.province string required

The Canadian province or territory in the delivery address.

Example ON

data.ship_to.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

data.ship_to.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.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.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 unit_unconfirmed

data.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.address_verification.suggested_address.line1 string required

The street address.

Example 123 Sandbox Avenue

data.address_verification.suggested_address.line2 string or null required

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

Example null

data.address_verification.suggested_address.city string required

The city in the shipping address.

Example Toronto

data.address_verification.suggested_address.province string required

The Canadian province or territory in the delivery address.

Example ON

data.address_verification.suggested_address.postal_code string required

The Canadian postal code in the delivery address.

Example M5V 2T6

data.address_verification.suggested_address.country string required

ISO 3166-1 alpha-2 country code.

Example CA

data.lines array of object required

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

Show child fieldsHide child fields

data.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.lines[].sku_id integer required

Canonical TCGplayer SKU id (STABLE).

Example 14602

data.lines[].product_id integer required

Canonical TCGplayer product id (STABLE).

Example 86

data.lines[].quantity integer required

The number of units.

Example 1

data.lines[].unit_price integer required

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

Example 2499

data.lines[].name string or null required

Descriptive snapshot, frozen at order time (STABLE).

Example Abyssal Nightstalker

data.lines[].set string or null required

The card set or expansion.

Example Portal Second Age

data.lines[].condition string or null required

The normalized condition assigned to the card.

Example NM

data.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.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.lines[].language string or null

The language of the card printing.

Example English

data.lines[].finish string or null

The physical finish or foil treatment of the card.

Example Non-Foil

data.lines[].disclosures object

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

Show child fieldsHide child fields

data.lines[].disclosures.image_source string required

Who supplied the product image shown to the buyer.

Constraints: allowed values: catalog

data.lines[].disclosures.condition_source string required

Who assigned the displayed card condition.

Constraints: allowed values: seller_declared

data.lines[].disclosures.authenticity_source string required

Who supplied the authenticity determination.

Constraints: allowed values: seller_attestation

data.lines[].disclosures.snapcaster_inspected boolean required

Whether Snapcaster physically inspected the card.

Constraints: allowed values: false

data.lines[].disclosures.snapcaster_graded boolean required

Whether Snapcaster assigned the displayed grade.

Constraints: allowed values: false

data.lines[].disclosures.snapcaster_authenticated boolean required

Whether Snapcaster authenticated the card.

Constraints: allowed values: false

data.lines[].disclosures.grading_standard string required

The grading standard used for the declared grade.

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

The grade declared for the card under the named standard.

data.lines[].disclosures.buyer_protection string required

The buyer-protection coverage attached to this offering.

data.lines[].fulfillment_obligation object

The exact item characteristics the seller must fulfill.

Show child fieldsHide child fields

data.lines[].fulfillment_obligation.sku string required

The SKU that identifies the card variant.

Constraints: allowed values: exact

data.lines[].fulfillment_obligation.printing string required

The card printing the seller must supply.

Constraints: allowed values: exact

data.lines[].fulfillment_obligation.language string required

The language of the card printing.

Constraints: allowed values: exact

data.lines[].fulfillment_obligation.finish string required

The physical finish or foil treatment of the card.

Constraints: allowed values: exact

data.lines[].fulfillment_obligation.condition string required

The normalized condition assigned to the card.

Constraints: allowed values: declared-or-better

data.lines[].cancelled_quantity integer required

Constraints: minimum: 0 Example 0

data.lines[].refunded_quantity integer required

Constraints: minimum: 0 Example 0

data.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.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.lines[].substitution.request_id integer required

The fulfillment report that last rewrote this line.

data.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.lines[].substitution.original.sku_id integer required

See Canonical catalog in Core concepts.

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

See Canonical catalog in Core concepts.

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

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

The card set or expansion.

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

The normalized condition assigned to the card.

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

The language of the card printing.

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

The physical finish or foil treatment of the card.

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

The rarity assigned to the card printing.

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

data.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.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.totals.subtotal integer required

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

Example 2499

data.totals.shipping integer required

The shipping charge or delivery details for the order.

Example 599

data.totals.tax integer required

The tax total or breakdown applied to the order.

Example 403

data.totals.grand_total integer required

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

Example 3501

data.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.tax.lines array of object required

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

Show child fieldsHide child fields

data.tax.lines[].label string required

Example HST

data.tax.lines[].rate number required

The decimal tax rate applied to the taxable amount.

Example 0.13

data.tax.lines[].amount integer required

The monetary amount in minor currency units.

Example 403

data.shipping object

The shipping charge or delivery details for the order.

Show child fieldsHide child fields

data.shipping.method string required

Example Tracked parcel

data.shipping.cost integer required

The shipping cost in minor currency units.

Example 599

data.shipping.is_tracked boolean or null required

Example true

data.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.status string required

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

data.fulfillment OrderFulfillment

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

Show child fieldsHide child fields

data.fulfillment.tracking_company string required

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

data.fulfillment.tracking_number string required

Carrier tracking number (STABLE).

data.fulfillment.tracking_url string or null required

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

data.updated_at string required

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

data.dispatch object required

Show child fieldsHide child fields

data.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.dispatch.dispatched_at string or null required

Constraints: format: date-time Example null

data.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.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.cancellations array of object required

Show child fieldsHide child fields

data.cancellations[].id string required

data.cancellations[].created_at string required

Constraints: format: date-time

data.cancellations[].lines array of object required

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

Show child fieldsHide child fields

data.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.cancellations[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

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

The number of units.

Constraints: exclusive minimum: 0

data.cancellations[].payment_refund object or null required

Show child fieldsHide child fields

data.cancellations[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.cancellations[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.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.refunds array of object required

Show child fieldsHide child fields

data.refunds[].id string required

data.refunds[].created_at string required

Constraints: format: date-time

data.refunds[].lines array of object required

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

Show child fieldsHide child fields

data.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.refunds[].lines[].sku_id integer required

See Canonical catalog in Core concepts.

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

The number of units.

Constraints: exclusive minimum: 0

data.refunds[].payment_refund object or null required

Show child fieldsHide child fields

data.refunds[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.refunds[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.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.refunds[].restock boolean required

Whether fulfilled units return to on-hand inventory.

data.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.substitutions[].id string required

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

data.substitutions[].request_id integer required

The fulfillment report the buyer accepted.

data.substitutions[].created_at string required

When the buyer accepted the report.

Constraints: format: date-time

data.substitutions[].lines array of object required

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

Show child fieldsHide child fields

data.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.substitutions[].lines[].original_sku_id integer required

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

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

The number of units.

Constraints: exclusive minimum: 0

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

How to resolve this issue.

Constraints: allowed values: remove, substitute

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

The SKU that ships instead. Null on a removal.

data.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.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.substitutions[].payment_refund.amount integer required

The monetary amount in minor currency units.

data.substitutions[].payment_refund.currency string required

The ISO 4217 currency code used for monetary amounts.

data.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.pending_cancellation_requests array of object required

Show child fieldsHide child fields

data.pending_cancellation_requests[].id string required

data.pending_cancellation_requests[].created_at string required

Constraints: format: date-time

data.pending_cancellation_requests[].reason string or null required

data.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.pending_cancellation_requests[].lines[].line_ref string required

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

See Canonical catalog in Core concepts.

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

The number of units.

Constraints: exclusive minimum: 0

data.reason string required

Why the event fired. address_verified: a terminal address verification verdict landed on the customer address (read address_verification). address_corrected: the seller wrote an address correction (read ship_to; it is now that correction). line_substituted: the buyer accepted the seller’s offer to ship a different version of a card that could not go out as ordered, so a line’s sku_id and card details were rewritten (read lines; pick and pack from them). items_added, not yet sent because order additions are not yet available: the buyer paid for additional cards on this order, so lines now carries one or more new entries - each with its own line_ref, possibly repeating a sku_id already on the order - and shipping.method is the parcel’s effective option if the addition bought an upgrade. Pack everything in lines into the one existing parcel; the order’s dispatch deadline does not change. payment_refund_updated: the payment_refund.status of a cancellation, refund or substitution changed after its first event, in either direction, so the matching cancellations, refunds or substitutions entry has a new status (pending, succeeded or failed). Closed vocabulary, extended additively - tolerate values you do not handle (STABLE).

Constraints: allowed values: address_verified, address_corrected, line_substituted, items_added, payment_refund_updated Example address_corrected

Receiver response

200 - Return any 2xx after verifying the event and durably accepting it. With an orders subscription, a line_substituted event announces a sale: deduct its stock before you return 2xx. items_added will too once order additions are available.

Related