StoreOrderAdditionOfferResponse

Part of the response of POST /orders/{orderId}/addition-offers and POST /orders/{orderId}/addition-offers/{offerRef}/withdraw.

Type: object

Fields

success boolean required

Whether the operation completed as requested.

Constraints: allowed values: true Example true

data StoreOrderAdditionOffer required

The operation or event payload.

Show child fieldsHide child fields

data.offer_ref string required

The opaque public offer id (oao_…) - the {offerRef} of the withdraw and decline paths.

Example oao_9e2b7c4d1a6f43b8a5c0d3e7f1b8a264

data.status string required

sent and accepted are the two OUTSTANDING states: accepted means the buyer approved the exact amount and a payment is in flight, which is why the offer can no longer be withdrawn, replaced or expired. withdrawn is the seller taking it back; declined is the buyer’s answer; expired is the 24 hours running out; replaced is a different offer sent in its place; paid means the payment succeeded and the cards are now purchases on the order; payment_blocked means a captured payment was screened out and returned. Every ending is one-way, and every one but paid frees the stock the offer held - paid converts it into the purchase.

Constraints: allowed values: sent, accepted, withdrawn, declined, expired, replaced, paid, payment_blocked Example sent

data.lines OrderAdditionOfferLine[] required

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

Show child fieldsHide child fields

data.lines[].sku_id integer required

The exact printing offered. Everything beside it is frozen from it.

Example 14602

data.lines[].product_id integer required

See Canonical catalog in Core concepts.

Example 86

data.lines[].quantity integer required

The number of units.

Example 2

data.lines[].reference_unit_price_cents integer required

The seller’s live listing price when the offer was authored: the ceiling this offer was allowed to charge up to, and the “was” price a discount reads against.

Example 450

data.lines[].unit_price_cents integer required

What this offer charges per unit; at or below the reference.

Example 400

data.lines[].name string or null required

Example Abyssal Nightstalker

data.lines[].set_name string or null required

Example Portal Second Age

data.lines[].condition string or null required

The normalized condition assigned to the card.

Example Near Mint

data.lines[].category_name string or null required

Example Magic: The Gathering

data.lines[].language string or null required

The language of the card printing.

Example English

data.lines[].finish string or null required

The catalog’s printing, under the name the order line snapshot uses.

Example Normal

data.lines[].collector_number string or null required

Example null

data.lines[].rarity string or null required

The rarity assigned to the card printing.

Example Uncommon

data.money OrderAdditionOfferMoney required

Show child fieldsHide child fields

data.money.currency string required

The ISO 4217 currency code used for monetary amounts.

Example CAD

data.money.merchandise_cents integer required

The offered cards, AFTER any seller discount.

Example 800

data.money.reference_merchandise_cents integer required

The same cards at the seller’s listing prices; above merchandise_cents by the discount.

Example 900

data.money.shipping_cents integer required

The shipping DIFFERENCE over shipping already paid for this parcel. EXACTLY 0 when the combined remaining quantities still fit the shipping option already paid for - nothing extra is charged for carriage the buyer has. Otherwise it is the shipping_upgrade option’s price less every shipping amount this parcel has already collected, including earlier paid upgrades, so a second upgrade never re-charges the first.

Example 0

data.money.purchase_fee_cents integer required

The buyer purchase fee at the ORIGINAL order’s frozen rate, on the discounted merchandise.

Example 28

data.money.tax_cents integer required

Example 104

data.money.total_cents integer required

The EXACT amount the buyer would pay - the sum of the four components above, frozen for the offer’s whole validity period. Nothing may accept for a different figure.

Example 932

data.money.tax_lines array of object required

Show child fieldsHide child fields

data.money.tax_lines[].label string required

Example HST

data.money.tax_lines[].rate number required

The decimal tax rate applied to the taxable amount.

Example 0.13

data.money.tax_lines[].amount integer required

The monetary amount in minor currency units.

Example 104

data.shipping_upgrade OrderAdditionOfferShippingUpgrade or null required

The shipping option this addition would UPGRADE the parcel to, or null when it rides the one already paid for. All purchased additions share the original parcel: there is never a second shipment. The upgrade becomes the order’s effective option and tracking requirement only when the payment succeeds, and the historical shipping charges are not rewritten - each stays on the payment that collected it. The amount is money.shipping_cents.

Show child fieldsHide child fields

data.shipping_upgrade.method string required

The upgraded option’s label, in the wording an order’s shipping method uses.

data.shipping_upgrade.is_tracked boolean required

Whether the upgraded option requires tracking when the order is marked shipped.

data.note string or null required

The seller’s own words beside the quote; null when none was given.

Example Two more, at the price you paid

data.request_ref string or null required

The buyer request this offer answered, or null when the seller offered directly.

Example oar_5c1e9a7f3b2d48e6a0f4c8d1b7e3a925

data.support_case_id integer or null required

Example null

data.replaces_offer_ref string or null required

The offer this one replaced, or null when it replaced none.

Example null

data.sent_at string required

Example 2026-09-04T19:14:03.000Z

data.expires_at string required

When the offer and its stock hold stop being valid: 24 hours after sent_at. Show it.

Example 2026-09-05T19:14:03.000Z

data.resolved_by_party string or null required

Who ended it - buyer on a decline, seller on a withdrawal or replacement, system on expiry, which belongs to nobody. Null while outstanding.

Constraints: allowed values: buyer, seller, operator, system, null Example null

data.resolved_at string or null required

Example null

data.resolution_note string or null required

Example null

data.payment OrderAdditionPayment or null required

The buyer’s payment for this offer, or null until one accepts it.

Show child fieldsHide child fields

data.payment.payment_ref string required

The opaque public payment id (oap_…).

data.payment.status string required

processing means the answer is not in yet - a browser redirect does not prove a payment succeeded, so keep asking. succeeded means the cards are on the order. failed means the attempt collected nothing and the offer can be accepted again. blocked means a captured payment was screened out and returned; this offer is over.

Constraints: allowed values: processing, succeeded, failed, blocked

data.payment.currency string required

The ISO 4217 currency code used for monetary amounts.

data.payment.amount_cents integer required

The exact amount the buyer approved, frozen from the offer.

data.payment.accepted_at string required

data.payment.completes_at string required

When this attempt’s 15-minute completion window closes - distinct from the offer’s own 24 hours. Past it a processing payment is UNKNOWN rather than failed, and is reconciled against the provider.

data.payment.resolved_at string or null required

data.payment.failure_reason string or null required

data.payment.attempts integer required

Above 1 when a declined card was retried on the same payment.

data.seller_fees OrderAdditionOfferSellerFees required

Show child fieldsHide child fields

data.seller_fees.commission_cents integer required

Commission on the discounted merchandise, capped per UNIT at the order’s frozen cap.

Example 40

data.seller_fees.processing_fee_cents integer required

Processing on the WHOLE additional payment - purchase fee and tax included - plus one fixed component for this one payment. It is never reapplied to the original capture.

Example 57

data.seller_fees.platform_collected_tax_cents integer required

Example 0

data.seller_fees.fee_terms object required

The five terms this quote was priced at: the ORDER’s frozen terms as captured, never today’s Marketplace settings. An order that cannot prove all five cannot carry an addition at all.

Show child fieldsHide child fields

data.seller_fees.fee_terms.marketplace_fee_rate_basis_points integer required

Example 500

data.seller_fees.fee_terms.marketplace_fee_per_item_cap_cents integer required

Example 2500

data.seller_fees.fee_terms.purchase_fee_rate_basis_points integer required

Example 350

data.seller_fees.fee_terms.processing_fee_rate_basis_points integer required

Example 290

data.seller_fees.fee_terms.processing_fee_fixed_cents integer required

Example 30

Used by

• POST /orders/{orderId}/addition-offers - Send or replace an add-on offer (not yet available) (response)
• POST /orders/{orderId}/addition-offers/{offerRef}/withdraw - Withdraw an add-on offer (not yet available) (response)