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

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"}

Was this page helpful?