---
title: What changed for deposits and redemptions
description: The built deposit and redemption contract for partner integrations, with each change marked additive or breaking and the action an integrator must take.
sidebar:
  order: 6
---

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](/deposits-and-redemptions) 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.

:::note[Availability]
These changes are available in the TEST environment. Player deposits are off
in Production until Stashtab enables them, and Production refuses a player
deposit until then. The [environment guide](/environments) explains which
host and test identity apply to your integration. A TEST response does not
prove a live carrier, label or token effect.

In TEST, the scheduled steps (dispute reminders, the deadline ship-back and
its order) do not yet run on their own daily or hourly clock. Stashtab runs
them on request while you test them. Configured Test inventory supports
redemptions with explicit lines. Published pack lookup and pack-based creation
require Live mode.
:::

Every HTTP operation below has the same MCP tool. The
[MCP tool catalog](/warehouse-mcp-tools.json) 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](#a-return-address-on-every-player-deposit) | Breaking | Send `returnAddress` when you create or preview a player deposit. |
| [Declared condition or `conditionDeferred` per line](#a-declared-condition-or-conditiondeferred-on-each-line) | Additive | Put the declared condition variant on each line, or set `conditionDeferred: true`. |
| [Sealed unit and magnetic holder per line](#deposit-services-on-each-line) | Breaking | Send `sealedUnit` on every sealed line of a player deposit. Optionally send `magneticSlab` on a raw-card line. |
| [Per-card intake outcomes](#what-happens-to-each-card-at-intake) | Behavior change | Expect a disputed card to be missing from the acceptance handoff until it is resolved. |
| [Dispute list, resolution and event feed](#disputed-cards-list-resolve-and-follow-events) | Additive | Read disputes, send the player's choice, and read the event feed. |
| [30-day clock and automatic ship-back](#the-30-day-clock-and-automatic-ship-back) | Additive | Accept the new order kind `ship_back` in order reads. |
| [Deposit video on escalation](#deposit-video-on-escalation) | No API change | Send escalations through your support team. |
| [`variantSku` and `unitRefs` in the acceptance handoff](#the-acceptance-handoff-names-each-card) | Additive | Tokenize from `variantSku` and keep each `unitRef`. |
| [Deferred graded-card capabilities](#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](#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](#delivery-times) | No API change | Show the static ranges on the first screen. Use shipping quotes at checkout. |
| [Redemption packing exceptions (November 17, 2026)](#redemption-packing-exceptions) | 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.

- Reference: [Create a purchase order](/reference/purchase-orders/create-purchase-order-customer),
  [Preview a purchase order](/reference/purchase-orders/preview-purchase-order-customer).
- Example: [Mark a purchase order as a player deposit](/examples#mark-a-purchase-order-as-a-player-deposit).

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

- Reference: [Create a purchase order](/reference/purchase-orders/create-purchase-order-customer),
  [Read a purchase order](/reference/purchase-orders/get-purchase-order-customer),
  [Correct a deposit declaration](/reference/purchase-orders/correct-purchase-order-declaration-customer).
- Example: [Mark a purchase order as a player deposit](/examples#mark-a-purchase-order-as-a-player-deposit).

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

- Reference: [Create a purchase order](/reference/purchase-orders/create-purchase-order-customer),
  [Preview a purchase order](/reference/purchase-orders/preview-purchase-order-customer).
- Example: [Mark a purchase order as a player deposit](/examples#mark-a-purchase-order-as-a-player-deposit).

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

- Example: [Resolve a player deposit's disputed cards](/examples#resolve-a-player-deposits-disputed-cards).

## 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](/reference/deposit-disputes/list-deposit-disputes) | `GET /v1/organizations/{orgId}/deposit-disputes` | `deposit_disputes_list` |
| [Resolve one dispute](/reference/deposit-disputes/resolve-deposit-dispute) | `POST /v1/organizations/{orgId}/deposit-disputes/{disputeId}/resolution` | `deposit_disputes_resolve` |
| [Read dispute events](/reference/deposit-disputes/list-deposit-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.

- Example: [Resolve a player deposit's disputed cards](/examples#resolve-a-player-deposits-disputed-cards).

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

- Reference: [Read an order](/reference/orders/get-order-customer),
  [List orders](/reference/orders/list-orders-customer).
- Example: [Resolve a player deposit's disputed cards](/examples#resolve-a-player-deposits-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

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](/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](/reference/reports/get-warehouse-report-customer).
- Example: [Observe acceptance, opening and corrections safely](/examples#observe-acceptance-opening-and-corrections-safely).

## 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](/deposits-and-redemptions) and
[contract-checked examples](/examples#customer-enabled-deposit-and-redemption-handoffs)
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.

- Reference: [Create a redemption order](/reference/orders/create-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](/examples#prepare-and-create-a-current-redemption).

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

- Guide: [Redemption packing exceptions](/packing-exceptions), with a
  [Test walkthrough](/packing-exceptions#test-walkthrough).
- Reference: [Read an order](/reference/orders/get-order-customer),
  [Read orders in a batch](/reference/orders/batch-get-orders),
  [Answer a packing exception](/reference/orders/answer-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](/reference/shipping-quotes/create-shipping-quote).

## Not in this change

Serialized packs are not part of this change.
