Create a refund

201

The refund was created. The response contains the updated order.

Response body: OrderResponse

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true

data PartnerOrderData required

The operation or event payload.

Show child fieldsHide child 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).

data.seller_id integer required

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

data.created_at string required

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

data.currency string required

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

data.customer OrderWebhookCustomer required

The buyer details saved when the order was created.

Show child fieldsHide child fields

data.customer.name string required

data.customer.email string required

The contact email address.

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.

data.customer.shipping_address.line2 string or null required

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

data.customer.shipping_address.city string required

The city in the shipping address.

data.customer.shipping_address.province string required

The Canadian province or territory in the delivery address.

data.customer.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

data.customer.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

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.

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.

data.ship_to.shipping_address.line2 string or null required

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

data.ship_to.shipping_address.city string required

The city in the shipping address.

data.ship_to.shipping_address.province string required

The Canadian province or territory in the delivery address.

data.ship_to.shipping_address.postal_code string required

The Canadian postal code in the delivery address.

data.ship_to.shipping_address.country string required

ISO 3166-1 alpha-2 country code.

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

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

data.lines[].sku_id integer required

Canonical TCGplayer SKU id (STABLE).

data.lines[].product_id integer required

Canonical TCGplayer product id (STABLE).

data.lines[].quantity integer required

The number of units.

data.lines[].unit_price integer required

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

data.lines[].name string or null required

Descriptive snapshot, frozen at order time (STABLE).

data.lines[].set string or null required

The card set or expansion.

data.lines[].condition string or null required

The normalized condition assigned to the card.

data.lines[].external_ref string or null required

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

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.

data.lines[].language string or null

The language of the card printing.

data.lines[].finish string or null

The physical finish or foil treatment of the card.

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

data.lines[].refunded_quantity integer required

Constraints: minimum: 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

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.

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.

data.totals.shipping integer required

The shipping charge or delivery details for the order.

data.totals.tax integer required

The tax total or breakdown applied to the order.

data.totals.grand_total integer required

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

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

data.tax.lines[].rate number required

The decimal tax rate applied to the taxable amount.

data.tax.lines[].amount integer required

The monetary amount in minor currency units.

data.shipping object

The shipping charge or delivery details for the order.

Show child fieldsHide child fields

data.shipping.method string required

data.shipping.cost integer required

The shipping cost in minor currency units.

data.shipping.is_tracked boolean or null required

data.buyer_notes string

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

data.status string required

Constraints: allowed values: created, 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).

data.updated_at string required

Constraints: format: date-time

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

data.dispatch.dispatched_at string or null required

Constraints: format: date-time

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

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

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