Order created

After a buyer checks out, Snapcaster creates one order per seller and POSTs an order.created event to each seller's platform webhook endpoint. Use seller_id to route the event to the right store. The body is frozen when the order is created, and a retry repeats the same payload bytes, with one exception: if Snapcaster corrects a guest buyer's mistyped email, every delivery after the correction, including a retry of this event, carries the corrected customer.email. Keeping the original bytes would hand the mistyped address, which belongs to someone else, to your integration. In this event, ship_to always equals the customer snapshot and address_verification is always pending, even if a seller correction or a verification verdict has landed since. Those changes and a corrected email reach you through GET /orders, where the order appears again with a new updated_at and the current ship_to, address_verification and customer. Verify the signature and deduplicate by event_id. Deliveries may repeat or arrive out of order. See https://developers.snapcaster.ca/guide/webhook-signing and https://developers.snapcaster.ca/guide/path-b#delivery-semantics for verification and retry handling. Fields are marked STABLE or PROVISIONAL. Ignore unknown fields.

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.created event.

Payload type: OrderCreatedEvent

Envelope fields

event_id string required

A globally unique event id that stays the same across retries. Use it to deduplicate deliveries (STABLE).

Example evt_sandbox_01K4A90CFV7X8B2MD6J3H5Q1ZR

type string required

The event type. Future order lifecycle events use the same envelope (STABLE).

Constraints: allowed values: order.created Example order.created

created_at string required

ISO-8601 UTC instant the event was generated; unchanged across retries (STABLE).

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

data OrderCreatedData 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 4

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 pending

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.

data.address_verification.suggested_address.line2 string or null required

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

data.address_verification.suggested_address.city string required

The city in the shipping address.

data.address_verification.suggested_address.province string required

The Canadian province or territory in the delivery address.

data.address_verification.suggested_address.postal_code string required

The Canadian postal code in the delivery address.

data.address_verification.suggested_address.country string required

ISO 3166-1 alpha-2 country code.

data.lines OrderWebhookLine[] required

One or more line snapshots (STABLE).

Constraints: minimum items: 1

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.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 selected shipping option. method is free text, and cost is integer cents matching totals.shipping (STABLE).

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

The current order status. This field is absent until the first status change; absence means created. An order.created delivery never includes it (STABLE).

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

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).

Receiver response

200 - Return any 2xx after verifying the event and durably accepting it. With an orders subscription this 2xx acknowledges the sale's stock, so deduct the sold cards before you return it.

Related