Contract-checked examples
Contract-checked customer reads, imports, deposit and redemption request shapes, accepted report metadata, and unknown outcomes.
These synthetic values are checked against the registered operation input and error schemas in the repository. They demonstrate request shape, not a live provider response or a grant to call another organization. Replace the sample IDs with IDs returned under your current authority. The generated reference owns the full operation inventory; the authentication guide owns client setup.
The current deposit/redemption rollout covers raw-card condition assessment, sealed goods and ordinary redemptions. Graded-card deposits, certificate lookups and exact-slab redemptions are deferred. No graded-card, certificate-lookup or exact-slab request example is published. Use the current walkthrough and capability matrix for the supported flow.
Read current organization scope
GET /v1/organizations lists only the current caller’s authorized
organizations. For an explicitly selected customer, use
GET /v1/organizations/{orgId}. A caller-supplied ID never widens scope.
{}
Page through inventory
GET /v1/organizations/{orgId}/inventory?limit=50 returns a bounded page.
When nextCursor is non-null, pass that opaque value unchanged as cursor.
Do not stop solely because the current page has fewer than 50 rows. The
same arguments go to MCP inventory_list.
{
"organizationId": "org_example",
"limit": 50,
"cursor": "opaque-cursor-from-previous-page"
}
For a first page, omit cursor. An inventory quantity that is unavailable is
null, never an invented zero.
Export the complete bounded result
GET /v1/organizations/{orgId}/inventory/export returns a customer-safe CSV
download for the same search. MCP inventory_export uses the same arguments
and returns the complete file content as structured result. An oversized export
fails instead of returning a truncated success.
{
"organizationId": "org_example",
"q": "sample sku"
}
Filter and export orders by Tag
A Tag is one optional customer-defined value per order for grouping, filtering and billing attribution. It is separate from a shipping label document and from warehouse-owned ShipStation tags.
The API keeps the compatible customerLabel JSON field and query parameter.
For example, GET /v1/organizations/{orgId}/orders?customerLabel=Fall%20mailer
matches that exact Tag. The Orders page keeps its existing label URL filter
parameter.
GET /v1/organizations/{orgId}/orders/export?customerLabel=Fall%20mailer
exports the same filtered orders. The machine CSV column remains
customer_label; its values are Tags.
To set, change or clear this value, keep the existing
PUT /v1/organizations/{orgId}/orders/{orderId}/customer-label endpoint or
MCP orders_label tool. Its customerLabel field accepts one value; null
clears it. Current permissions and revision checks still apply.
Preview and submit an exact order import
POST /v1/organizations/{orgId}/order-imports/preview parses one source and
reviews a page without creating orders. This structured JSON example has one
synthetic row. The real preview response supplies the import ID, source
revision, group ID and revision, review ID and revision. A row becomes ready
only after its current product and address checks pass. Previewing the same
source again returns any row it already sent as it was sent, with submitted
set to its recorded outcome and its order number when one was recorded; that
row is not checked again and is never ready again.
{
"organizationId": "org_example",
"limit": 25,
"offset": 0,
"rateContext": {
"carrierIds": ["carrier_example"],
"shipFrom": {
"addressLine1": "1 Example Street",
"addressLine2": "",
"city": "Toronto",
"company": "",
"country": "CA",
"email": "",
"name": "Example Warehouse",
"phone": "",
"postalCode": "M5V 1A1",
"region": "ON"
}
},
"source": {
"format": "json",
"orders": [{
"items": [{ "name": "Example item", "quantity": 1, "sku": "EXAMPLE-1" }],
"recipient": {
"addressLine1": "2 Example Street",
"addressLine2": "",
"city": "Toronto",
"company": "",
"country": "CA",
"email": "",
"name": "Example Recipient",
"phone": "",
"postalCode": "M5V 1A2",
"region": "ON"
},
"sourceOrderId": "external-example-1"
}]
}
}
For HTTP, put org_example in the path and omit organizationId from the
JSON body. For MCP order_imports_preview, keep it in the tool arguments.
POST /v1/organizations/{orgId}/order-imports/{importId}/submissions sends
only the exact reviewed groups selected by the caller. Use values from the
latest preview and persisted import results, not the illustrative IDs below.
Every selected group is rechecked; an excluded group stays unsubmitted.
{
"organizationId": "org_example",
"importId": "import_example",
"selectedGroups": [{
"groupId": "group_example",
"groupRevision": 1,
"reviewId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"reviewRevision": 1,
"sourceRow": 1
}],
"submissionKey": "example-intent-1"
}
After submission, GET /v1/organizations/{orgId}/order-imports/{importId}
reads customer-safe source and per-group outcomes. It does not submit another
group or repair an unknown provider outcome.
{
"organizationId": "org_example",
"importId": "import_example"
}
Observe an unknown result without retrying
This is the shape of an error that may carry the existing operation ID. The
provider_outcome_unknown code does not mean rejected or confirmed. Preserve
the ID and read the outcome while still authorized; do not resubmit, change
keys, or overlap the same intent.
{
"error": {
"code": "provider_outcome_unknown",
"message": "The provider outcome is not established.",
"operationId": "00000000-0000-0000-0000-000000000000"
},
"meta": { "requestId": "req_example" }
}
GET /v1/organizations/{orgId}/operations/{operationId} and MCP
operations_get are read-only. They recheck current authority, so a revoked
caller cannot inspect an old receipt.
{
"organizationId": "org_example",
"operationId": "00000000-0000-0000-0000-000000000000"
}
The MCP request wraps a registered tool name and the same arguments:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "inventory_list",
"arguments": { "organizationId": "org_example", "limit": 50 }
}
}
Customer-enabled deposit and redemption handoffs
The examples below use illustrative organization, product and record IDs. They bind to the registered Warehouse customer operations; there is no customer-specific API namespace. They do not establish an external account, permission or environment availability. Your current customer grant, verified product/source bindings, supported label origin/service and the capability matrix decide whether an operation is available. Use IDs and revisions returned by your own authorized reads. A mutation needs its own stable submission key; never change the key to retry an unknown effect. The deposit and redemption walkthrough puts these steps in order.
Mark a purchase order as a player deposit
The registered customer route is
POST /v1/organizations/{orgId}/purchase-orders; MCP uses
purchase_orders_create. Put org_example in the HTTP path and omit
organizationId from its JSON body. The MCP arguments include it. The
player_deposit kind marks the PO as goods a player is sending in to be
tokenized and records the external deposit ID (depositRef) on the same PO; it is
a declaration, not proof of physical arrival, stock or report acceptance.
Player deposits are off by default: staff turn them on per customer, and a
customer without the setting gets forbidden. A supported prepaid tracked label
requires the configured origin and service. The isolated TEST adapter returns
providerVerified: false. A real label and external deposit readback remain
unverified. Leave out poNumber and Vault assigns the customer’s next
PO number, such as EXAMPLE-PO-0001; the response returns the PO number used.
A poNumber you send instead must be unused by that customer.
A player deposit also needs a returnAddress (name, street, city, postal code
and two-letter country): a card that cannot be accepted ships back there. Set
conditionDeferred: true on a line, without a condition, to accept the
warehouse’s assessed condition for those cards instead of declaring one.
Each sealed line needs sealedUnit (pack, box or case), so its intake
bills per started 24 packs, per box or per case; a sealed line without it is
refused as validation_error. A raw-card line can set magneticSlab
(branded, or branded_tamper_seal for a tamper-resistant seal) to put each
card in a branded magnetic holder. The fees come from your rate card.
{
"organizationId": "org_example",
"registrationKind": "player_deposit",
"depositRef": "deposit-example-1",
"lines": [
{ "productId": "product_example", "quantity": 1, "magneticSlab": "branded" },
{ "productId": "product_example_sealed", "quantity": 24, "sealedUnit": "pack" }
],
"returnAddress": {
"name": "Example Player",
"addressLine1": "1 Example Street",
"city": "Toronto",
"region": "ON",
"postalCode": "M5V 2T6",
"countryCode": "CA"
},
"submissionKey": "deposit-example-1"
}
To edit the declaration before acceptance, read the current PO, then submit the
complete current line set with its expectedDeclarationRevision to
PATCH /v1/organizations/{orgId}/purchase-orders/{purchaseOrderId} or MCP
purchase_orders_declaration_correct. This is revision checked; it never
rewrites physical counts or an accepted report. A standard customer PO edit
remains unavailable where its provider update cannot be verified.
{
"organizationId": "org_example",
"purchaseOrderId": "00000000-0000-4000-8000-000000000011"
}
{
"organizationId": "org_example",
"purchaseOrderId": "00000000-0000-4000-8000-000000000011",
"expectedDeclarationRevision": 1,
"lines": [{
"lineId": "line_example",
"productId": "product_example",
"declaredQuantity": 2
}],
"submissionKey": "deposit-edit-example-1"
}
Mix raw cards and sealed goods in one deposit
One player deposit can combine supported raw-card and sealed-good lines. This deposit declares one LP card in a branded magnetic holder, leaves the condition of three raw cards to the warehouse and sends one sealed box. Each line names a different product. Raw-card lines name a condition-variant product: the declared card’s LP variant, and any variant for the deferred raw-card line.
{
"organizationId": "org_example",
"registrationKind": "player_deposit",
"depositRef": "deposit-example-3",
"lines": [
{ "productId": "product_example_card_lp", "quantity": 1, "magneticSlab": "branded" },
{ "productId": "product_example_card_b", "quantity": 3, "conditionDeferred": true },
{ "productId": "product_example_box", "quantity": 1, "sealedUnit": "box" }
],
"returnAddress": {
"name": "Example Player",
"addressLine1": "1 Example Street",
"city": "Toronto",
"region": "ON",
"postalCode": "M5V 2T6",
"countryCode": "CA"
},
"submissionKey": "deposit-example-3"
}
Observe acceptance, opening and corrections safely
Warehouse staff record actual arrivals and condition counts. Count saving alone does not accept goods or post stock. After finality and discrepancy settlement, staff acceptance must establish the complete source, stock and accepted report effect. A genuine late box corrects the same PO and report, applying stock only for the late lines. Staff opening capture and accepted-content correction preserve the original opening identity and immutable revision history; a stale, rejected or unknown correction cannot replace the current accepted revision. These staff actions are not customer or limited-service calls.
Acceptance delivers the accepted purchase-order content to your configured
report receiver. The schema is PurchaseOrderAcceptanceReport in the OpenAPI
components. For a player deposit, this content is the acceptance confirmation
to tokenize from. Each line names every accepted card once in unitRefs. It
also gives the condition-variant SKU (variantSku) that the cards are held
under. A unit reference stays the same when staff correct a card’s condition;
the next report revision gives the new variantSku. A card that is held in a
condition dispute is not in the content until its dispute releases it.
variantSku is null only for goods that have no condition variant, such as
sealed product. This synthetic content shows two accepted NM cards on one
line. It is not a real external delivery.
{
"depositRef": "deposit-example-1",
"kind": "purchase_order",
"lines": [{
"assessedCondition": "nm",
"declarationLineRef": "00000000-0000-4000-8000-000000000044",
"externalCatalogRef": "17",
"productId": "00000000-0000-4000-8000-000000000055",
"quantity": 2,
"sourceItemRef": "17",
"unitRefs": [
"00000000-0000-4000-8000-000000000066:0",
"00000000-0000-4000-8000-000000000066:1"
],
"variantSku": "CARD-17-NM"
}],
"purchaseOrderId": "00000000-0000-4000-8000-000000000011"
}
An authorized customer or granted service can read accepted report metadata at
GET /v1/organizations/{orgId}/reports/{reportId} or MCP reports_get.
Pass ?revision=1 to read an exact accepted historical revision; omit it for
the current accepted revision. The read omits report content, source revision
IDs, submission identities, private evidence and integration references.
Unaccepted reports are unavailable. This synthetic response illustrates the
customer-safe projection and is not a real external acknowledgement.
{
"organizationId": "org_example",
"reportId": "00000000-0000-4000-8000-000000000022"
}
{
"currentAcceptedRevision": 2,
"reportId": "00000000-0000-4000-8000-000000000022",
"revision": {
"acceptedAt": "2026-09-30T12:00:00Z",
"acknowledgementRef": "test-ack-example-2",
"expectedAcceptedRevision": 1,
"externalAcceptedRevision": 2,
"recordedAt": "2026-09-30T12:00:01Z",
"revision": 2
},
"source": {
"kind": "purchase_order",
"purchaseOrderId": "00000000-0000-4000-8000-000000000011"
}
}
Resolve a player deposit’s disputed cards
At acceptance, each received card is compared with the player’s declaration.
A card that the warehouse assessed worse than declared, or a card that was not
declared, opens a condition dispute for that one card. The rest of the deposit
is accepted. A disputed card stays in custody, but it is not in the acceptance
report, so it does not mint. If no instruction arrives within 30 days of
openedAt, the card ships back to the deposit’s return address automatically.
The deadlineAt field gives that time.
List the disputed cards with
GET /v1/organizations/{orgId}/deposit-disputes or MCP
deposit_disputes_list. The default status is open; add purchaseOrderId
to read one deposit. Each dispute’s unitRef names the physical card with the
same reference the acceptance report uses, so an accepted card appears in the
next report revision under its own unitRef.
{
"organizationId": "org_example",
"purchaseOrderId": "00000000-0000-4000-8000-000000000011",
"status": "open"
}
Send the player’s choice for one card to
POST /v1/organizations/{orgId}/deposit-disputes/{disputeId}/resolution or
MCP deposit_disputes_resolve. accept_and_tokenize accepts the card at the
assessed condition and confirms the next revision of the deposit’s accepted
report with the card in it. That revision is the acceptance confirmation that
mints. ship_back records that the card returns to the player; it stays out
of every later report. Within a day, the warehouse creates one Ready order
that ships that card to the deposit’s return address. It appears in your
orders with kind ship_back. When it ships, your open invoice gets the
per-shipment ship-back fee and the label’s postage at cost. Each dispute is
resolved once. The same instruction again returns
the dispute unchanged, and a different instruction gets state_conflict. If
the report outcome is rejected, unavailable or unknown, the dispute stays open.
Warehouse staff can also carry out your instruction for you. The dispute then
shows resolvedBy warehouse; your own instructions show request.
{
"organizationId": "org_example",
"disputeId": "00000000-0000-4000-8000-000000000033",
"resolution": "accept_and_tokenize",
"submissionKey": "dispute-resolve-example-1"
}
To follow disputes without polling the list, read the event feed at
GET /v1/organizations/{orgId}/deposit-disputes/events?after=0 or MCP
deposit_dispute_events_list. Each dispute emits dispute.opened, then
dispute.reminder 7 days before its deadline while it is still open, then
dispute.resolved with outcome accepted, shipped_back_by_request or
shipped_back_automatically. Store the returned checkpoint and send it as
after on your next read. Events never change; read the dispute list for the
current state.
{
"organizationId": "org_example",
"after": 0
}
Prepare and create a current redemption
Use the generated references as the schema-checked source for the current
request shapes: preview an order,
get shipping quotes and
create a redemption order. Direct
line-based requests remain supported for raw cards and sealed goods. A raw
card line names its exact recorded condition; a sealed-good line has
condition: null.
First preview the real recipient address, items and physical source with
orderKind: "redemption", then choose a priced shipping service from the
current quote. Pass the returned
fulfillmentSource, requestedShippingService,
requestedShippingServiceReview and shippingQuote unchanged to creation.
The quote is an estimate, not a price lock or a label purchase. A changed
recipient, items, source, parcel plan, service or rate needs a new review.
For cards from a published pack, look up the pack and build explicit redemption lines. Use the returned product IDs and conditions for the whole pack or the cards the player selected.
New redemption creation starts the native order On hold. Its confirmed creation
receipt can include cancellation.deadlineAt and cancellation.eligible as
the server-recorded one-hour window. Replaying the same key returns the
original receipt and does not extend that deadline. When the order is
released, Vault buys no shipping label; the warehouse buys it after packing,
and its tracking appears on later order reads. Cancellation and release remain
subject to separate provider and account proof; do not represent this receipt
as insurance, cancellation or physical-fulfillment acceptance.
Save the submission key, exact request, order reference, correlation ID and operation ID. Reuse the same key only for the same intent. If the outcome is unknown, use the authorized order and operation outcome reads; do not alter the key or resend the request.
Professional grading, grader-cert lookup and exact-slab redemption are deferred. Configured Test workspaces support line-based redemption with simulated stock. Published pack preview requires Live mode.
Product configuration
See the product configuration guide for authority, physical-stock distinctions and the separate flag/component verification steps.
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001"}
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","unitLabel":"boxes","unitsPerCarton":20,"unitsPerCase":10,"expectedRevision":0,"submissionKey":"packaging-example-001"}
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","expectedRevision":"2026-10-10T00:00:00Z","components":[{"productId":"00000000-0000-4000-8000-000000000002","quantity":2}]}
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","expectedRevision":"2026-10-10T00:00:00Z","isBundle":true,"submissionKey":"bundle-example-001"}