What changed for deposits and redemptions
The built deposit and redemption contract for partner integrations, with each change marked additive or breaking and the action an integrator must take.
These notes replace the planned deposit and redemption shapes that we shared earlier. They describe the final, built contract. Where the built contract differs from the plan, the section says so. The deposit and redemption walkthrough shows the whole flow step by step.
Two terms are used on this page:
- Deposit: a player sends physical cards to the warehouse, and the accepted cards become tokens.
- Redemption: a token ships out to the player as a physical card.
Every HTTP operation below has the same MCP tool. The MCP tool catalog has the matching schemas. Fees are set on your rate card; this page gives no prices.
Summary
| Change | Type | What you must do |
|---|---|---|
| Return address on every player deposit | Breaking | Send returnAddress when you create or preview a player deposit. |
Declared condition or conditionDeferred per line |
Additive | Put the declared condition variant on each line, or set conditionDeferred: true. |
| Sealed unit and magnetic holder per line | Breaking | Send sealedUnit on every sealed line of a player deposit. Optionally send magneticSlab on a raw-card line. |
| Per-card intake outcomes | Behavior change | Expect a disputed card to be missing from the acceptance handoff until it is resolved. |
| Dispute list, resolution and event feed | Additive | Read disputes, send the player’s choice, and read the event feed. |
| 30-day clock and automatic ship-back | Additive | Accept the new order kind ship_back in order reads. |
| Deposit video on escalation | No API change | Send escalations through your support team. |
variantSku and unitRefs in the acceptance handoff |
Additive | Tokenize from variantSku and keep each unitRef. |
| Deferred graded-card capabilities | Deferred | Do not integrate professional grading, certificate lookup or exact-slab redemption in the current rollout. |
correlationId in the redemption result |
Deprecation | Read correlationId from the redemption result. The earlier field stays as a deprecated alias for now. |
| Regional delivery ranges | No API change | Show the static ranges on the first screen. Use shipping quotes at checkout. |
| Redemption packing exceptions (November 17, 2026) | Additive | Accept packingException in redemption reads, poll held redemptions hourly and send each card’s answer. |
Deposits
A return address on every player deposit
BreakingA player deposit now requires returnAddress. Vault uses it only to ship
back a card that is not accepted. The address needs name, addressLine1,
city, postalCode and a two-letter countryCode. companyName,
addressLine2, region, phone and email are optional. Vault stores the
address on the purchase order and does not change it later.
What you must do: send returnAddress on every player deposit. Create and
preview refuse a player deposit without it as validation_error on the
returnAddress path. A standard purchase order must not carry a return
address.
- Reference: Create a purchase order, Preview a purchase order.
- Example: Mark a purchase order as a player deposit.
A declared condition or conditionDeferred on each line
AdditiveEach deposit line names a product. For cards, that product is a condition
variant, such as the LP variant of a card, so the line declares that
condition. To leave the grade to the warehouse, set conditionDeferred: true
on the line. The warehouse grade is then final, and the card never disputes.
A deferred line reads back with declaredCondition: null.
Changed from the plan: there is no separate condition field when you create
the deposit. The line’s condition-variant product is the declaration. To change
a declaration before acceptance, use the declaration correction, which takes
declaredCondition.
What you must do: choose the condition-variant product that the player
declared, or set conditionDeferred: true. conditionDeferred is refused on
a standard purchase order.
- Reference: Create a purchase order, Read a purchase order, Correct a deposit declaration.
- Example: Mark a purchase order as a player deposit.
Deposit services on each line
BreakingEach current player-deposit line can carry two supported fields. They set how the deposit is billed. The amounts come from your rate card.
| Field | Values | Where it applies |
|---|---|---|
sealedUnit |
pack, box or case |
Required on each line of a sealed product. Refused on a card line. |
magneticSlab |
branded or branded_tamper_seal |
Optional on a raw-card line. Each card on the line goes in its own branded magnetic holder. branded_tamper_seal adds a tamper-resistant seal. Refused on a sealed line. |
After the warehouse accepts the deposit, the next daily run adds one intake charge to your invoice. Raw cards bill for each started group of 25. Packs bill for each started group of 24. Boxes and cases bill for each one. A started group bills in full for each deposit purchase order. For example, 26 cards bill as two groups. A late arrival after the first acceptance does not add a second intake charge.
A magnetic holder bills for each card when the warehouse records the work. Cards in a magnetic holder have a monthly storage charge for each holder. They are not part of the cubic-foot storage charge.
What you must do: send sealedUnit on each sealed line of a player deposit.
Create and preview refuse a sealed line without it as validation_error on
the lines.<i>.sealedUnit path. Send magneticSlab only when the player
asks for one. Both fields are refused on a standard purchase order.
- Reference: Create a purchase order, Preview a purchase order.
- Example: Mark a purchase order as a player deposit.
What happens to each card at intake
Behavior changeAt acceptance, the warehouse compares each received card with the player’s declaration:
| What the warehouse finds | Result |
|---|---|
The player set conditionDeferred |
Accepted at the warehouse grade. The grade is final. |
| The grade is the same as or better than declared | Accepted at the warehouse grade. |
| The grade is worse than declared | A condition dispute opens for that card (assessed_worse). |
| A card that the player did not declare | A condition dispute opens for that card (undeclared_extra). |
| A declared card is not in the package | Not received. Nothing is accepted for it. |
Disputes are per card, never per package. The other cards in the package are accepted and can be tokenized. The handoff always gives the warehouse grade, not the player’s declaration. A disputed card stays in custody, but it is not in the acceptance handoff. Thus it is not tokenized until its dispute resolves.
What you must do: do not expect every received card in the first acceptance
handoff. If every card in a deposit is disputed, no handoff is sent until a
dispute resolves as accept_and_tokenize or a late arrival adds an accepted
card.
Disputed cards
Disputed cards: list, resolve and follow events
AdditiveThree new operations let your platform handle each disputed card:
| Operation | HTTP | MCP |
|---|---|---|
| List disputes | GET /v1/organizations/{orgId}/deposit-disputes |
deposit_disputes_list |
| Resolve one dispute | POST /v1/organizations/{orgId}/deposit-disputes/{disputeId}/resolution |
deposit_disputes_resolve |
| Read dispute events | GET /v1/organizations/{orgId}/deposit-disputes/events |
deposit_dispute_events_list |
The list returns open disputes by default. Filter by purchaseOrderId or
status. Each dispute gives declaredCondition, assessedCondition,
reason, unitRef, openedAt and deadlineAt.
The resolution takes resolution and a submissionKey:
accept_and_tokenize: the player accepts the warehouse grade. The card is added to the next revision of the deposit’s acceptance handoff, which is the confirmation to tokenize from.ship_back: the card goes back to the deposit’s return address.
A dispute resolves once. The same instruction again returns the dispute with
no new effect. A different instruction gets state_conflict. If the handoff
outcome is rejected, unavailable or unknown, the dispute stays open.
resolvedBy tells you who resolved the dispute: request for your own
instruction, warehouse when warehouse staff carried out an instruction for
you, and automatic for the 30-day ship-back.
Changed from the plan: events are a pull feed, not a push webhook. Read the
feed with after set to your last checkpoint. The event types are final:
| Event | When |
|---|---|
dispute.opened |
The dispute opened at acceptance. |
dispute.reminder |
7 days before deadlineAt, while the dispute is still open. |
dispute.resolved |
The dispute resolved. outcome is accepted, shipped_back_by_request or shipped_back_automatically. |
Each dispute emits each event type at most once. Events never change; read the dispute list for the current state.
What you must do: show each disputed card to the player, send the player’s choice, and store the event checkpoint.
The 30-day clock and automatic ship-back
AdditiveEach disputed card has its own 30-day clock. It starts at openedAt, and
deadlineAt is openedAt plus 30 days. The reminder does not reset the
clock. If no instruction arrives by deadlineAt, the next daily run resolves
the dispute as shipped_back_automatically.
Every ship-back, whether requested, done by the warehouse for you or automatic,
becomes one Ready order to the deposit’s return address. The order has the
new kind ship_back. It is not a redemption or a reship. Several cards from
one deposit ship as separate orders, one for each card. When the ship-back
order has its shipping label, your invoice gets the per-shipment ship-back fee
and the label’s postage at cost. You decide whether to pass these on to
players.
What you must do: accept ship_back as an order kind in order reads and
lists. If your client checks the full list of order kinds, add it.
- Reference: Read an order, List orders.
- Example: Resolve a player deposit’s disputed cards.
Deposit video on escalation
No API change.
The warehouse records one video for each deposit package and keeps it with that deposit. The video is private and is not shown to players up front. When a player escalates a dispute through your support team, bring it to your shared support channel with Stashtab. We share the video there as a Google Drive link.
Changed from the plan: we share a Drive link, not a time-limited link. No API operation returns the video.
Acceptance handoff
The acceptance handoff names each card
AdditiveThe acceptance handoff is the report that the warehouse delivers to your configured receiver when it accepts cards. Each line now also has:
variantSku: the condition-variant SKU of the line, such asCARD-17-NM. It is null only for goods with no condition variant, such as sealed product.unitRefs: one reference for each accepted card on the line, in the form<receiptLineId>:<unitIndex>.
A unitRef stays the same when staff correct a card’s condition. The next
handoff revision then gives the new variantSku. A card that a dispute
releases comes back under its own unitRef. The schema is the
PurchaseOrderAcceptanceReport component in the OpenAPI reference.
What you must do: tokenize from variantSku, and keep each unitRef with its
token to reconcile later acceptance revisions.
- Reference: Read accepted report metadata.
- Example: Observe acceptance, opening and corrections safely.
Deferred graded-card capabilities
DeferredProfessional grading, graded-card certificate lookup and exact-slab redemption are deferred from the current integration rollout. This page previously described released schema shapes for those capabilities. Retained fields are historical compatibility details only; they do not make the capability available and are not an operational recipe. Use the deposit and redemption walkthrough and contract-checked examples for the supported raw-card, sealed-goods and ordinary-redemption flow.
Redemptions
correlationId in the redemption result
DeprecationThe redemption result now returns the integration correlation as
correlationId. The earlier partner-named field is deprecated. It is still
returned, with the same value as correlationId, so a client that reads it
continues to work. Stashtab will announce a date before it removes that field.
What you must do: read correlationId from the result of a redemption order.
Stop reading the deprecated field before its announced removal date.
- Reference: Create a redemption order.
No change to condition-exact redemptions
Condition-exact redemptions work as before: name the product and its condition on each redemption line.
- Example: Prepare and create a current redemption.
Redemption packing exceptions
AdditiveAdded November 17, 2026. Available in Test. In Live, the warehouse cannot
record an exception yet, and Live answers stay received.
When the warehouse cannot pack a redemption card as ordered, it holds the
order and records a packing exception. Single and batch order reads of a
redemption now include packingException. The field is null when no card
was held. Each held copy of a card is its own unit, with an offer, a 168-hour
response deadline, a decision and an outcome. The new answer operation sends
the player’s choice for one unit: accept_offer or remove_card.
- A stale offer revision is refused with
stale_offerand changes nothing. - The same submission key and body return the original answer. A replay never answers a newer offer.
- An unanswered unit is removed at its deadline.
- An applied removal is the evidence to restore that card’s token.
estimateis the revised customer estimate. It is never a charge, and an unknown amount isnull, never zero. A higher estimate needs no approval. Actual charges arrive on your ordinary invoices.
What you must do: accept the new optional packingException field in
redemption reads. Read each redemption that has not shipped at least once an
hour. Send each player’s answer with the new operation, and restore a token
only after its removal is applied.
- Guide: Redemption packing exceptions, with a Test walkthrough.
- Reference: Read an order, Read orders in a batch, Answer a packing exception.
Delivery times
No API change.
For the first screen of your redemption flow, use these typical ranges. They are business days from order to doorstep, and include about one day of preparation.
| Region | Business days, order to doorstep |
|---|---|
| United States | 3–6 |
| Canada | 4–8 |
| Europe | 5–8 |
| Asia | 5–10 |
| Latin America | 7–14 |
| Rest of world | 7–14 |
These ranges are typical, not promised. At checkout, use the ETA from a
shipping quote instead. Each quote gives delivery.days and delivery.date
from the carrier. Each value is null when the carrier does not supply it.
- Reference: Get shipping quotes.
Not in this change
Serialized packs are not part of this change.