---
title: Contract-checked examples
description: Contract-checked customer reads, imports, deposit and redemption request shapes, accepted report metadata, and unknown outcomes.
sidebar:
  order: 5
---

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](/reference) owns the full operation inventory; the
[authentication guide](/authentication) 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](/deposits-and-redemptions) and
[capability matrix](/authentication#integration-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.

```json title="example:organizations-list"
{}
```

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

```json title="example: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.

```json title="example:inventory-export"
{
  "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.

```json title="example:order-import-preview"
{
  "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.

```json title="example:order-import-submit"
{
  "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.

```json title="example:order-import-results"
{
  "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.

```json title="example:unknown-error"
{
  "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.

```json title="example:operation-outcome-read"
{
  "organizationId": "org_example",
  "operationId": "00000000-0000-0000-0000-000000000000"
}
```

The MCP request wraps a registered tool name and the same arguments:

```json title="example:mcp-inventory-call"
{
  "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](/authentication#integration-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](/deposits-and-redemptions)
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.

```json title="example:deposit-register"
{
  "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.

```json title="example:deposit-po-read"
{
  "organizationId": "org_example",
  "purchaseOrderId": "00000000-0000-4000-8000-000000000011"
}
```

```json title="example:deposit-edit"
{
  "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.

```json title="example:deposit-register-mixed"
{
  "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.

```json title="example:acceptance-handoff"
{
  "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.

```json title="example:report-read"
{
  "organizationId": "org_example",
  "reportId": "00000000-0000-4000-8000-000000000022"
}
```

```json title="example:accepted-report-result"
{
  "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`.

```json title="example:dispute-list"
{
  "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`.

```json title="example:dispute-resolve"
{
  "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.

```json title="example:dispute-events"
{
  "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](/reference/orders/preview-order),
[get shipping quotes](/reference/shipping-quotes/create-shipping-quote) and
[create a redemption order](/reference/orders/create-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](/deposits-and-redemptions#2-resolve-a-whole-pack-or-selected-cards). 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](/reference/orders/get-order-customer) and
[operation outcome](/reference/operations/get-warehouse-operation-outcome-customer)
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](/product-configuration) for authority,
physical-stock distinctions and the separate flag/component verification steps.

```json title="example:product-configuration-read"
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001"}
```

```json title="example:product-packaging-configure"
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","unitLabel":"boxes","unitsPerCarton":20,"unitsPerCase":10,"expectedRevision":0,"submissionKey":"packaging-example-001"}
```

```json title="example:product-bundle-prepare"
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","expectedRevision":"2026-10-10T00:00:00Z","components":[{"productId":"00000000-0000-4000-8000-000000000002","quantity":2}]}
```

```json title="example:product-bundle-set"
{"organizationId":"org_example","productId":"00000000-0000-4000-8000-000000000001","expectedRevision":"2026-10-10T00:00:00Z","isBundle":true,"submissionKey":"bundle-example-001"}
```
