Deposit and redemption walkthrough
Build and test your platform's player deposit, condition dispute, ship-back, and redemption flows.
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. Every HTTP operation has the same MCP tool; the MCP tool catalog has the matching schemas. The contract-checked examples 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 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 atdata.preview. The paginated dispute list returns rows directly in thedataarray and puts the next cursor inmeta.nextCursor. Keepmeta.requestIdwhen 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
forbiddenwhen 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 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 existingoperationIdif returned and observe it through the read-only outcome route. See Outcomes and errors. - Fees. Read your rate card 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. 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.
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, Create a purchase order.
- Example: 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, Correct a deposit declaration.
- Example: 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.
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 asCARD-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. 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.
- Example: 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, Resolve one dispute.
- Example: Resolve a player deposit’s 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.
- Example: Resolve a player deposit’s 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, Read an order, 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, Get shipping quotes, Create a redemption order.
2. Resolve a whole pack or selected cards
- Call Preview pack redemption with
the
deploymentRefandpackReferencefor the published opening. OmitcardOrdinalsto read the whole pack. Each row incardshas its one-basedordinal, exact VaultproductId, and recordedcondition. Copy the condition as returned. A no-damage-found assessment usescondition: null. - Create a redemption order with
explicit
lines. For the whole pack, use the returnedlinesdirectly. For a subset, select the matching rows fromcards, group repeated cards with the sameproductIdand condition, and send one line per product withproductId,condition, andquantity. 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. 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, Read an order, Read an operation outcome.
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 has the fields, the answer operation and a Test walkthrough.
- Reference: Read an order, Answer a 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
- 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.
- 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.
- Choose
accept_and_tokenizefor one dispute andship_backfor 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. - Create a redemption from configured Test inventory using explicit lines. Check the saved products, conditions, quantities, and on-hold state.
- 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.