Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

Breaking

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

A declared condition or conditionDeferred on each line

Additive

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

Deposit services on each line

Breaking

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

What happens to each card at intake

Behavior change

At 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

Additive

Three 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

Additive

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

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

Additive

The 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 as CARD-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.

Deferred graded-card capabilities

Deferred

Professional 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

Deprecation

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

No change to condition-exact redemptions

Condition-exact redemptions work as before: name the product and its condition on each redemption line.

Redemption packing exceptions

Additive

Added 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_offer and 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.
  • estimate is the revised customer estimate. It is never a charge, and an unknown amount is null, 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.

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.

Not in this change

Serialized packs are not part of this change.

Was this page helpful?