---
title: Deposit and redemption walkthrough
description: Build and test your platform's player deposit, condition dispute, ship-back, and redemption flows.
sidebar:
  order: 5.5
---

Use this guide to build deposit and redemption in your platform. Your
platform owns the player experience and token records. Vault owns warehouse
receiving, assessed condition, stock, and fulfillment.

Two terms are used on this page:

- **Deposit**: a player sends physical items to the warehouse, and the
  accepted items become tokens.
- **Redemption**: a token ships out to the player as a physical item.

Each step links to its HTTP route in the [API reference](/reference). Every
HTTP operation has the same MCP tool; the
[MCP tool catalog](/warehouse-mcp-tools.json) has the matching schemas. The
[contract-checked examples](/examples#customer-enabled-deposit-and-redemption-handoffs)
have request bodies for each step. Fees come from your rate card. This page
gives no prices.

## Before you start

- **Connect from your backend.** Use the released Vault host, organization and
  mode assigned to your integration. TEST uses that same shared host and
  organization model; it is not a separate customer origin or identity. Keep
  credentials on your server and check the [authentication guide](/authentication)
  for the current operation and mode matrix. An unavailable TEST operation
  must remain unavailable: it never falls back to Live.
- **Read the HTTP response envelope.** For the JSON operations in this
  walkthrough, read the result under `data`. A deposit preview is at
  `data.preview`. The paginated dispute list returns rows directly in the
  `data` array and puts the next cursor in `meta.nextCursor`. Keep
  `meta.requestId` when you need to trace a request.
- **Player deposits are a customer setting.** Stashtab turns player deposits
  on for each customer. A customer without the setting gets `forbidden` when
  it creates or previews a player deposit.
- **Availability is scoped.** A customer setting, credential permission,
  organization, mode and verified source can each refuse an operation. The
  [environment guide](/environments) describes environment identity; it is not
  an approval to perform a provider, warehouse or customer effect.
- **Evidence has boundaries.** An API receipt, quoted amount or established
  tracking fact does not prove an insured label, a canceled provider order,
  physical picking, carrier handoff, delivery, receiver acceptance or token
  activity. Those require their own authorized account, provider and physical
  workflow evidence.
- **Submission keys.** For each operation that takes a `submissionKey`,
  save the key with the exact request before sending it. A confirmed request
  can be replayed with the same key and body. If the outcome is unknown, keep
  the existing `operationId` if returned and observe it through the read-only
  [outcome route](/reference/operations/get-warehouse-operation-outcome-customer).
  See [Outcomes and errors](/reliability).
- **Fees.** [Read your rate card](/reference/rate-card/get-customer-rate-card-customer)
  for the deposit, storage and ship-back rates that apply to you.

## What to store in your platform

| Record | What to keep | How you use it |
| --- | --- | --- |
| Deposit | Your player and deposit IDs, the Vault purchase-order ID, and the last declaration revision | Show the player their deposit status and submit declaration corrections against the current revision. |
| Accepted item | The deposit, accepted `unitRef`, and latest `variantSku` | Apply an acceptance revision once per unit. A grade correction updates the same item. |
| Dispute | Dispute ID, `unitRef`, current state, and `deadlineAt` | Show the player the assessed grade and send their resolution. Save your event checkpoint after processing a batch. |
| Redemption | Your redemption ID, Vault order reference and `correlationId` | Reconcile the order and show warehouse status and tracking to the player. |

Keep TEST and Production records and credentials separate. If your
integration receives an acceptance revision more than once, use the
deposit and `unitRef` to recognize a unit you have already tokenized.

## Player deposit

### 1. Build the deposit lines

One player deposit can mix raw cards and sealed goods. Each line names one
product once. Choose the line shape from what the player sends:

| The player sends | Line | Rules |
| --- | --- | --- |
| A raw card with a declared condition | The card's condition-variant product, such as its LP variant | The variant is the declaration. Optional `magneticSlab`. |
| A raw card and leaves the grade to the warehouse | Any one of the card's condition-variant products, with `conditionDeferred: true` | The variant's condition is ignored. The warehouse grade is final. The card never disputes. Optional `magneticSlab`. |
| A sealed pack, box or case | The sealed product with `sealedUnit` (`pack`, `box` or `case`) | `sealedUnit` is required. Sealed items are not graded. |

The warehouse grades raw cards on the TCGplayer condition standard: NM, LP,
MP, HP and DMG. See the
[TCGplayer Card Conditioning Overview](https://help.tcgplayer.com/hc/en-us/articles/221430307-Card-Conditioning-Overview).
DMG is an
ordinary grade: a DMG card is accepted and tokenized, unless the player
declared a better condition, and then it disputes. Sealed items stay sealed.
The warehouse checks them for damage and does not grade them. A damaged
sealed item is still accepted; it does not dispute.

`magneticSlab` (`branded`, or `branded_tamper_seal` for a tamper-resistant
seal) puts each raw card on the line in its own branded magnetic holder. It is
refused on a sealed line. Professional grading, grader-cert lookups and
exact-slab deposits or redemptions are deferred. Do not send a graded-item
request or treat a historical schema field as enabled work.

- Example: [Mark a purchase order as a player deposit](/examples#mark-a-purchase-order-as-a-player-deposit).

### 2. Create the deposit

Send the lines with `registrationKind: "player_deposit"`, your deposit ID in
`depositRef` and the player's `returnAddress`. The return address needs
`name`, `addressLine1`, `city`, `postalCode` and a two-letter `countryCode`.
Vault uses it only to ship back a card that is not accepted, and never changes
it. To check a deposit first, preview it with the same body but no
`submissionKey`. A preview creates nothing. A receipt identifies the submitted
operation; it is not proof of label purchase, physical receipt or acceptance.

If you send the same request again with the same `submissionKey`, Vault
returns the stored result. A changed request conflicts. If the outcome is
unknown, keep the key and operation ID and observe the result; do not submit a
new request to force another effect.

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

### 3. Correct the declaration before acceptance

To change a declared condition or quantity before the warehouse accepts the
deposit, read the purchase order, then send the complete current line set
with its `expectedDeclarationRevision`. A stale revision is refused.

- Reference: [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).

### 4. Arrival and intake

The warehouse records one video of each deposit package as it opens it, and
keeps the video with that deposit. Staff count each item and grade each raw
card. Counting does not accept anything. When counting is final, staff
accept the deposit, and each received card is compared with the declaration:

| What the warehouse finds | Result |
| --- | --- |
| The line 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 dispute opens for that card (`assessed_worse`). |
| A card that the player did not declare | A dispute opens for that item (`undeclared_extra`). |
| A declared item is not in the package | Not received. Nothing is accepted for it. |

Disputes are per card, never per package. The other items in the package are
accepted. The purchase-order read shows the counted quantities by condition,
the variance from the declaration and any undeclared items.

- Reference: [Read a purchase order](/reference/purchase-orders/get-purchase-order-customer).

### 5. Tokenize from the acceptance handoff

At acceptance, Vault produces the acceptance facts that your platform uses for
tokenization. Each line gives:

- `variantSku`: the condition-variant SKU that the cards are held under, such
  as `CARD-17-NM`. It is the warehouse grade, never the player's declaration.
  It is null only for goods with no condition variant, such as sealed items.
- `unitRefs`: one reference for each accepted unit on the line.

Keep each `unitRef` with its token. A `unitRef` never changes. If staff
correct a card's grade, the next handoff revision gives the new `variantSku`
under the same `unitRef`. A disputed card is not in the handoff until its
dispute resolves as `accept_and_tokenize`. If every card in a deposit is
disputed, no handoff is sent until one resolves as `accept_and_tokenize`.

You can read the metadata of each accepted handoff revision. The read does
not return the handoff content.

You can also [poll the deposit's assessment and accepted units](/polling#read-deposit-assessment-and-accepted-units).
That read separates assessment from acceptance, withholds disputed and
ship-back units, and returns stable unit references with the recorded variant
SKU or an explicit unavailable mapping. Polling is available independently of
notifications; report metadata alone is not the accepted unit content.

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

### 6. Resolve disputed cards

A disputed card stays in custody but does not mint. The player chooses one
of two outcomes for each disputed card, and your platform sends that choice:

- `accept_and_tokenize`: the player accepts the warehouse grade. The card is
  added to the next revision of the acceptance handoff, which is the
  confirmation to tokenize it.
- `ship_back`: the card goes back to the deposit's return address.

List the disputes to show each card to the player. Each dispute gives
`declaredCondition` (null for an undeclared item), `assessedCondition`,
`reason`, `unitRef`, `openedAt` and `deadlineAt`. A dispute resolves once. The
same choice again returns the dispute with no new effect. A different choice
gets `state_conflict`. If the handoff for an `accept_and_tokenize` choice is
rejected, unavailable or unknown, the dispute stays open.

Warehouse staff can also send a choice for you. The dispute then shows
`resolvedBy: "warehouse"`. Your own choices show `request`, and the 30-day
ship-back shows `automatic`.

- Reference: [List disputes](/reference/deposit-disputes/list-deposit-disputes),
  [Resolve one dispute](/reference/deposit-disputes/resolve-deposit-dispute).
- Example: [Resolve a player deposit's disputed cards](/examples#resolve-a-player-deposits-disputed-cards).

### 7. Follow dispute events and the 30-day clock

Each disputed card has its own 30-day clock. It starts at `openedAt`, and
`deadlineAt` is `openedAt` plus 30 days. Read the event feed with `after` set
to your last `checkpoint` to follow each dispute without polling the list:

| When | Event | What it means |
| --- | --- | --- |
| Acceptance | `dispute.opened` | A card is disputed. The rest of the deposit is in the handoff. |
| 7 days before `deadlineAt` | `dispute.reminder` | The dispute is still open. The clock does not reset. |
| You or the warehouse send `accept_and_tokenize` | `dispute.resolved` with `outcome: "accepted"` | The card is in the next handoff revision. |
| You or the warehouse send `ship_back` | `dispute.resolved` with `outcome: "shipped_back_by_request"` | A ship-back order follows. |
| `deadlineAt` passes with no choice | `dispute.resolved` with `outcome: "shipped_back_automatically"` | The daily run ships the card back. |

Each dispute emits each event type at most once. Events never change; read
the dispute list for the current state.

- Reference: [Read dispute events](/reference/deposit-disputes/list-deposit-dispute-events).
- Example: [Resolve a player deposit's disputed cards](/examples#resolve-a-player-deposits-disputed-cards).

### 8. Ship-back orders and charges

Every ship-back, whether the player asked for it, the warehouse sent it for
you or the deadline passed, becomes one Ready order to the deposit's return
address. The next daily run creates the order. The order has
`kind: "ship_back"`. It is not a redemption. Several cards from one deposit
ship as separate orders, one for each card. Read the order for its tracking.

After the ship-back order has a live label with a readable ship date and
cost, the next daily run records two billable work lines: the per-shipment
ship-back fee and the label's postage at cost. They appear on an invoice
after the warehouse applies the reviewed charges. You decide whether to
pass these on to players.

- Reference: [List orders](/reference/orders/list-orders-customer),
  [Read an order](/reference/orders/get-order-customer),
  [List invoice lines](/reference/billing/list-invoice-lines).

### 9. Escalations and the deposit video

The deposit video is private and is not shown to players up front. No API
operation returns it. Players contact your support team. When a player
escalates a dispute, your team brings it to your shared support channel with
Stashtab, and we share the video there as a Google Drive link.

## Redemption

### 1. Prepare the delivery and choose a priced service

Ordinary orders and redemptions use the same shipping preparation and provider
path. Start with the current recipient, exact fulfillment items and their
physical source. Preview the order, request a quote for that same recipient
and source, then choose one current service. A quote creates no order, reserves
no stock and does not lock a price. Changed recipient, items, conditions,
physical source, parcel plan, carrier configuration or rate requires a fresh
preview, quote and selection.

For a redemption, send `orderKind: "redemption"` in the order preview. Use a real
postal address in Test and Live. If the destination is rejected, needs review,
or could not be checked, resolve the issue and preview the final address again.
A quote and `autoAdvance` do not authorize placement. Create checks the exact
destination again before reserving inventory or sending an order.

Pass the returned `fulfillmentSource`, `requestedShippingService`,
`requestedShippingServiceReview` and `shippingQuote` unchanged to the
redemption request. The selected quote remains an estimate; this flow makes no
fixed-price, absorbed-difference or currency-conversion promise. Existing
explicit line-based redemption requests remain compatible, but a requested
quote must be reviewed again before the create effect.

Insurance is a separate choice from goods/customs declarations. Send
`insurance: { kind: "none" }` for no additional insurance. A supported native
choice names the insurer and one positive amount and currency for the
parcel. The quote returns its premium as `insuranceAmount`, separately from
`shippingAmount`, `fulfillmentAmount` and configured fees. Copy its complete
selection, including `insurance`, unchanged into creation. A different insurer,
value, currency or package plan requires a new quote.

Native options require current account, collectible, carrier, destination,
signature/claims and shipment-update evidence. Missing evidence makes the
option unavailable. Creating the redemption writes the chosen insurance to
the warehouse order as a coverage request for the label the warehouse buys
after packing. Vault does not buy the label or coverage itself. A quote,
request field or creation receipt does not establish insurance coverage; the
order's `current.insurance.label` shows the coverage the warehouse's label
reports, once it exists.

Delivery confirmation is independent from insurance and goods declarations.
Set `deliveryConfirmation` to `signature` or `adult_signature` in preview
and quote. The shared path also accepts `none`, `delivery`, and FedEx's
`direct_signature`. Omission means `none`. Restricted and other V2-only
modes are unavailable through this order path.

Copy the returned selection unchanged as `shippingQuote` on ordinary or
redemption creation. A supplied top-level `deliveryConfirmation` must match
that selection. A change requires a new quote and review; changed replay
content conflicts. The one-hour redemption hold still applies.

`confirmationAmount` reports the native fee and currency. It is an included
component of the shipping pricing basis. Do not add it to `totalAmount` again.
The customer shipping agreement still applies to the combined carrier cost or
retail comparison. No fixed or free signature fee is promised.

Non-default confirmation excludes Ground Saver, SurePost and Media Mail.
Omitted or `none` retains existing configured service behavior. Unsupported combinations are refused;
Vault never changes signature to adult signature, or either mode to none.
A failed provider lookup does not establish that a mode is unsupported.
Test confirmation is currently unavailable. A quote prices one parcel at the
order's total weight.

Order reads distinguish `current.requestedDeliveryConfirmation` from each
tracking entry's `deliveryConfirmation`. Missing or null shipment facts mean
unknown. Neither field proves recipient identity or physical delivery.

An ordinary API or MCP create starts On hold unless the request sets
`hold: false`, which releases it to the warehouse at once. A redemption enters the same creation module with its separate
redemption association and server-owned cancellation deadline. Neither buys a
shipping label: the warehouse buys it after packing, and its tracking appears
on later order reads.

- Reference: [Preview an order](/reference/orders/preview-order),
  [Get shipping quotes](/reference/shipping-quotes/create-shipping-quote),
  [Create a redemption order](/reference/orders/create-redemption-order).

### 2. Resolve a whole pack or selected cards

1. Call [Preview pack redemption](/reference/orders/preview-pack-redemption) with
   the `deploymentRef` and `packReference` for the published opening. Omit
   `cardOrdinals` to read the whole pack. Each row in `cards` has its one-based
   `ordinal`, exact Vault `productId`, and recorded `condition`. Copy the
   condition as returned. A no-damage-found assessment uses `condition: null`.
2. Create a [redemption order](/reference/orders/create-redemption-order) with
   explicit `lines`. For the whole pack, use the returned `lines` directly.
   For a subset, select the matching rows from `cards`, group repeated cards
   with the same `productId` and condition, and send one line per product with
   `productId`, `condition`, and `quantity`. Use those same lines throughout
   order preview and shipping quotes.

If the integration already knows which positions to ship, it can pass
`cardOrdinals` in the first call and use the returned `lines` for that subset.
The pack lookup reads the published contents. It does not reserve stock or
identify a specific physical copy. Creation checks current stock for the
selected products and conditions. Published pack lookup requires Live mode.

### 3. Create and observe a redemption

New redemption creation uses the shared order-creation module and starts the
native order **On hold**; that provider state has no client-created expiry.
Vault records the server-owned cancellation deadline as creation time plus one
hour. A newly confirmed creation receipt may include
`cancellation: { deadlineAt, eligible: true }`; that is a creation-time fact.
A replay returns the original receipt and never extends the deadline. Do not
use a client timer as the authority for current eligibility.

Read the current order before requesting cancellation. Its
`cancellation.eligible` reflects the persisted hold and server clock; the window
is open only while the current server time is strictly before `deadlineAt`.
The exact deadline is closed. Send the current `expectedRevision` and a stable
`submissionKey` to [Cancel an order](/reference/orders/cancel-order). Redemption
cancellation does not require the ordinary Ready-order picking acknowledgement.
Vault still checks the native order identity, revision and absence of an
established shipment, then confirms only from cancelled-order readback and its
receipt. Historical redemptions without a recorded hold return
`cancellation: null`; ordinary orders omit that field.

Test redemptions also return the server-owned cancellation deadline and current
time/state eligibility. These facts do not grant cancellation permission. The
dashboard keeps **Release** unavailable during that hour and explains when to
refresh. A direct early release returns `409 state_conflict` with the open-window
reason. After the deadline, refresh and review the current order before a manual
Test release. Expiry alone does not release a Test order.

The configured server timer releases a due hold through the owned provider
path to awaiting shipment, without a shipping label. Canceled and uncertain
redemptions are not released. An
armed or unknown cancellation/release is observed through its existing
submission rather than sent again. A due deadline is eligibility for release,
not evidence that release has occurred; scheduling and provider availability
can delay its completion. Use only the qualified environment assigned to your
integration. Software receipts do not establish stopped physical picking,
printed labels, carrier handoff, insurance coverage, refunds or token/escrow
changes.

Save the `submissionKey`, exact intent, order reference, `correlationId` and
any returned operation ID. The same key and intent may replay its stored
receipt. A changed intent conflicts. If the provider outcome is unknown,
observe the operation and order; never change the key or resend the intent to
force a label or order.

- Reference: [Create a redemption order](/reference/orders/create-redemption-order),
  [Read an order](/reference/orders/get-order-customer),
  [Read an operation outcome](/reference/operations/get-warehouse-operation-outcome-customer).

### 4. Use TEST without changing authority

Use the same released host, organization and Test mode as the rest of Vault.
Configured Test workspaces can create redemptions with explicit raw-card or
sealed-item lines and simulated stock reservations. When your Test workspace
has a configured copy of a published pack, call pack preview with its supplied
`deploymentRef` and `packReference`, then use the returned `lines` for the
line-based flow. Preview returns separate Test product IDs and preserves the
recorded raw-card conditions. It checks synthetic Test stock; it reserves none.

You can combine explicit lines from several previews with configured sealed
items. Preview and quote the complete basket before creation. The frozen `pack`
creation input still requires Live mode. A missing Test copy does not read a
Live pack instead, and a copied Production pack does not identify a different
staging pack or establish player-wallet ownership. Test receipts describe
simulated effects.

### 5. Answer packing exceptions

The warehouse can find a card that it cannot pack as ordered. Then it holds
the redemption and records one packing exception with a unit for each affected copy. Read
each redemption that has not shipped at least once an hour. Send the
player's answer for each copy: accept the offered replacement or remove the
card. A confirmed removal is the evidence to restore that card's token. The
[packing exceptions guide](/packing-exceptions) has the fields, the answer
operation and a Test walkthrough.

- Reference: [Read an order](/reference/orders/get-order-customer),
  [Answer a packing exception](/reference/orders/answer-packing-exception).

## Not covered

Professional grading, grader-cert lookups, exact-slab deposits and exact-slab
redemptions are deferred. Serialized-pack allocation, escrow, token
restoration and physical-copy custody are also outside this flow. Vault
confirms a packing-exception removal, but your platform restores the token.

## Verify your integration in TEST

1. Use the released shared TEST mode to read only the deposit and acceptance
   facts that its documented capabilities permit. Keep TEST records and
   credentials separate from Live records and credentials.
2. Arrange for the warehouse to receive the fixture with one accepted
   card and two cards graded below their declarations. Compare the PO,
   dispute list and accepted-unit polling result. Only accepted units should
   enter your token workflow.
3. Choose `accept_and_tokenize` for one dispute and `ship_back` for the
   other. Check that the first unit enters the next acceptance revision
   once. After the scheduled run, check for the return order for the second
   unit. Where sample rates and synthetic postage are configured, ask the
   warehouse to verify the two recorded billing lines. Exercise the automatic
   deadline path on a separate fixture with the warehouse.
4. Create a redemption from configured Test inventory using explicit lines.
   Check the saved products, conditions, quantities, and on-hold state.
5. Before using any provider workflow, obtain separately authorized evidence
   for the account, carrier, insurance, label, cancellation and physical
   fulfillment capabilities involved. Software and TEST proof do not supply
   that acceptance.
