OrderAdditionOfferEventData

Part of the payload of order.addition_offer.updated.

Type: object

Fields

offer_ref string required

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

Example oao_9e2b7c4d1a6f43b8a5c0d3e7f1b8a264

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

lines OrderAdditionOfferLine[] required

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

Show child fieldsHide child fields

lines[].sku_id integer required

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

Example 14602

lines[].product_id integer required

See Canonical catalog in Core concepts.

Example 86

lines[].quantity integer required

The number of units.

Example 2

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

lines[].unit_price_cents integer required

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

Example 400

lines[].name string or null required

Example Abyssal Nightstalker

lines[].set_name string or null required

Example Portal Second Age

lines[].condition string or null required

The normalized condition assigned to the card.

Example Near Mint

lines[].category_name string or null required

Example Magic: The Gathering

lines[].language string or null required

The language of the card printing.

Example English

lines[].finish string or null required

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

Example Normal

lines[].collector_number string or null required

Example null

lines[].rarity string or null required

The rarity assigned to the card printing.

Example Uncommon

money OrderAdditionOfferMoney required

Show child fieldsHide child fields

money.currency string required

The ISO 4217 currency code used for monetary amounts.

Example CAD

money.merchandise_cents integer required

The offered cards, AFTER any seller discount.

Example 800

money.reference_merchandise_cents integer required

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

Example 900

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

money.purchase_fee_cents integer required

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

Example 28

money.tax_cents integer required

Example 104

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

money.tax_lines array of object required

Show child fieldsHide child fields

money.tax_lines[].label string required

Example HST

money.tax_lines[].rate number required

The decimal tax rate applied to the taxable amount.

Example 0.13

money.tax_lines[].amount integer required

The monetary amount in minor currency units.

Example 104

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

shipping_upgrade.method string required

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

shipping_upgrade.is_tracked boolean required

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

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

request_ref string or null required

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

Example oar_5c1e9a7f3b2d48e6a0f4c8d1b7e3a925

support_case_id integer or null required

Example null

replaces_offer_ref string or null required

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

Example null

sent_at string required

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

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

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

resolved_at string or null required

Example null

resolution_note string or null required

Example null

payment OrderAdditionPayment or null required

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

Show child fieldsHide child fields

payment.payment_ref string required

The opaque public payment id (oap_…).

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

payment.currency string required

The ISO 4217 currency code used for monetary amounts.

payment.amount_cents integer required

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

payment.accepted_at string required

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.

payment.resolved_at string or null required

payment.failure_reason string or null required

payment.attempts integer required

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

seller_fees OrderAdditionOfferSellerFees required

Show child fieldsHide child fields

seller_fees.commission_cents integer required

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

Example 40

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

seller_fees.platform_collected_tax_cents integer required

Example 0

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

seller_fees.fee_terms.marketplace_fee_rate_basis_points integer required

Example 500

seller_fees.fee_terms.marketplace_fee_per_item_cap_cents integer required

Example 2500

seller_fees.fee_terms.purchase_fee_rate_basis_points integer required

Example 350

seller_fees.fee_terms.processing_fee_rate_basis_points integer required

Example 290

seller_fees.fee_terms.processing_fee_fixed_cents integer required

Example 30

order_id string required

The order the add-on is for (STABLE).

Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

seller_id integer required

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

Example 42

reason string required

What happened to the offer. sent: the seller sent it and its units are reserved. replaced: a newer offer named in replaces_offer_ref of its successor took its place and its reservation. withdrawn: the seller took it back. declined: the buyer refused it. expired: its 24 hours ran out. In each of those four endings its units are released. accepted: the buyer started paying, and the units stay reserved until the payment resolves. paid: the payment succeeded; order.updated with reason items_added announces the new lines. payment_failed: the attempt collected nothing and the offer is payable again until expires_at. payment_blocked: a captured payment was screened out and returned, and the offer is over (STABLE).

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

Used by

• order.addition_offer.updated - Add-on offer updated (not yet available) (payload)