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

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

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.

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.

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

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.

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.

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.

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.

2. Resolve a whole pack or selected cards

  1. Call 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 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. 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.

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.

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.

Was this page helpful?