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

Poll deposits and orders

Read customer-safe deposit and order facts with checkpoints, revision-aware ingestion, and safe retry handling.

Polling is a read-only way to observe the customer-safe facts Vault currently holds. It does not acknowledge an event, release an order, accept a deposit, or retry an earlier write. Use it to recover after a delayed or duplicate notification as well as for scheduled reconciliation.

Keep a separate checkpoint and deduplication store for every organization, mode, and stream. Current authority is checked on every request; a saved order ID, operation ID, or checkpoint never preserves access after its credential or membership is revoked.

Read order snapshots

Use POST /v1/organizations/{orgId}/orders/batch or MCP orders_batch_get when a poll has up to 20 order IDs. The HTTP body contains only orderIds; the organization is in the path. Results preserve the request order.

{
  "orderIds": ["order_example_1", "order_example_missing"]
}

The HTTP success envelope is always data plus meta.requestId:

{
  "data": {
    "items": [
      {
        "order": {
          "current": null,
          "customerLabel": null,
          "id": "order_example_1",
          "kind": "ordinary",
          "receipt": {
            "operationId": null,
            "recordedAt": "2026-11-05T15:00:00.000Z"
          },
          "sourceOrderId": null,
          "visibleOrderNumber": null
        },
        "orderId": "order_example_1",
        "status": "available"
      },
      {
        "orderId": "order_example_missing",
        "status": "missing"
      }
    ]
  },
  "meta": { "requestId": "req_example" }
}

available contains the same customer-safe detail as GET /v1/organizations/{orgId}/orders/{orderId} or MCP orders_get. Its current facts can be null when the warehouse no longer reports the order; that is different from missing. missing deliberately does not distinguish an unknown ID from an ID outside the caller’s current organization scope.

An unavailable result means Vault could not read that order’s current provider facts. Its optional retryAfterSeconds applies only to that ID:

{
  "orderId": "order_example_1",
  "retryAfterSeconds": 30,
  "status": "unavailable"
}

Wait at least that long before reading the ID again. A duplicate ID in one batch repeats its result at each requested position, but Vault reads it once. Do not turn the response array into an event log: retain each request position if it matters to your process, and compare later snapshots with your stored order facts.

Find redemption packing exceptions

An available redemption in a batch or single order read includes packingException. It is null when no card was held while packing. Poll each redemption that has not shipped at least once an hour, because the response deadline for each held card is 168 hours. The packing exceptions guide explains the fields and the answer operation.

Read carrier collection evidence

Individual and known-order batch reads include current.parcelEvidence when current order facts are available. HTTP and MCP return the same fields. Existing tracking[].carrier, number and shipDate fields keep their meaning.

allParcelsCollected is true only for a complete active outbound parcel set with qualifying evidence for every parcel. It is false for a complete set with a known pending parcel. It is null when Vault cannot establish the conclusion.

Field Meaning
coverage Whether the complete expected active parcel set is established.
state confirmed, pending, incomplete, stale, unavailable or unknown.
membershipObservedAt When Vault observed the native parcel membership.
parcels[].id Stable customer-safe parcel reference within this order.
parcels[].event Qualifying physical evidence, with its provider detail code.
parcels[].event.occurredAt Event time with an explicit timezone, or null.
parcels[].event.reportedAt Original reported event time, when available.
parcels[].establishedAt When Vault first retained this label’s qualifying evidence.
parcels[].observedAt Time of the latest tracking observation attempt.
parcels[].refresh Observation health, separate from historical evidence.
parcels[].simulated Whether the returned event is synthetic Test evidence.

COLLECTION_MADE and RECEIVED_BY_CARRIER establish carrier possession. Supported subsequent physical scans can also establish possession. Electronic advice, scheduled pickup, label creation, shipDate and aggregate shipped status do not establish collection. Unmapped detail codes remain unknown.

An earlier confirmed event can remain present after a failed refresh. Check refresh and the overall state before using that result. A timezone-less event keeps its reported time; Vault does not invent a UTC time.

Voided labels and return labels do not count toward outbound completeness. Replacement labels require their own evidence. Split shipments or package references that Vault cannot verify return an incomplete result. Unsupported account tracking returns unavailable evidence.

Additional-package scans need an unambiguous event time within the label’s lifetime. Older tracking history cannot establish collection for a new label.

Poll known order IDs through the existing bounded queue. Parcel observations refresh at most once per minute per order and become stale after five minutes. The shared provider budget and provider backoff can delay a refresh. Lists do not start per-parcel tracking reads.

Test shipment events use SIMULATED_SHIPMENT and simulated: true. A simulated shipment alone does not establish carrier collection. After you simulate carrier collection, each Test parcel shows a SIMULATED_COLLECTION event with simulated: true and the scan time. The Test order then reads state: confirmed and allParcelsCollected: true. The order status stays Shipped, as it does after a real collection scan. Live orders never use simulated events. Tracking reads change no order, stock or token state. Your integration owns any token action.

Read deposit assessment and accepted units

Use GET /v1/organizations/{orgId}/purchase-orders/{purchaseOrderId}/deposit-results or MCP purchase_orders_get_deposit_results for a known player-deposit PO. A current read-capable organization key may use the operation in its admitted mode. The HTTP result is under data:

{
  "data": {
    "purchaseOrderId": "00000000-0000-4000-8000-000000000001",
    "depositRef": "deposit_demo_1",
    "declarationRevision": 2,
    "assessment": [
      {
        "assessedCondition": "lp",
        "productId": "product_variant_lp_demo",
        "quantity": 1,
        "receiptLineId": "receipt_line_demo",
        "revision": 2,
        "unitRefs": ["receipt_line_demo:0"],
        "variantSku": { "kind": "available", "value": "CARD-DEMO-LP" }
      }
    ],
    "acceptance": { "kind": "current", "revision": 3, "items": [] }
  },
  "meta": { "requestId": "req_example" }
}

Here the unit has been assessed LP, but it is withheld from the accepted items. Assessment alone never authorizes tokenization. Current acceptance excludes open disputes and ship-backs; all units can be withheld even when the PO has an acceptance revision.

acceptance.kind is not_accepted before acceptance, or stale when the committed acceptance no longer matches current count revisions. Neither contains accepted items. A current acceptance contains only its accepted unit references. Its revision tracks commercial acceptance, not every change to accepted membership: resolving a dispute to accept-and-tokenize can add a unit at the same acceptance revision. Reconcile the full current accepted unitRefs on every successful poll, including after each dispute event; do not skip an unchanged revision. A stable unitRef identifies the same card; its count revision is reconciliation evidence. A changed count revision updates that same unit and does not authorize another mint. Keep a durable record of each unit and its applied facts so duplicate processing has no second business effect. Count revisions, declaration revision and acceptance revision are distinct.

variantSku.kind is available with the recorded condition-variant SKU, unavailable when that stored mapping is missing, or not_applicable for goods without a condition variant. Resolve an unavailable mapping before tokenization. Polling does not invent a SKU or make a live provider lookup. The read returns one consistent snapshot; it does not accept goods, deliver a report or reserve stock.

See the generated deposit-results reference for the complete response schema.

Read deposit disputes as a checkpointed stream

GET /v1/organizations/{orgId}/deposit-disputes/events?after=<checkpoint> and MCP deposit_dispute_events_list expose immutable dispute lifecycle events. For HTTP, the envelope is data and meta.requestId; the stream checkpoint is data.checkpoint, not the envelope metadata.

{
  "data": {
    "checkpoint": 1,
    "items": [
      {
        "deadlineAt": "2026-11-29T15:00:00.000Z",
        "depositRef": "deposit_demo_1",
        "disputeId": "dispute_demo_1",
        "eventId": "dispute_event_demo_1",
        "occurredAt": "2026-10-30T15:00:00.000Z",
        "outcome": null,
        "purchaseOrderId": "purchase_order_demo",
        "sequence": 1,
        "type": "dispute.opened"
      }
    ]
  },
  "meta": { "requestId": "req_example" }
}

Store { organizationId, mode, sequence } as the idempotency key and advance the saved checkpoint only after all returned items are durably ingested. If your ingestion fails, repeat the same after value; duplicate events are expected and must not repeat your downstream action. An empty response retains the checkpoint, so poll again with that same value. The stream reports dispute.opened, at most one dispute.reminder, and dispute.resolved; read the dispute list when the current dispute record is needed.

This stream is not an acceptance feed. A resolved dispute is not proof that a physical item was picked, handed to a carrier, delivered to a receiver, or tokenized. It also does not return the accepted deposit units. The accepted report-metadata read intentionally omits its handoff content; do not infer items, unitRefs, assessed conditions, or variant SKUs from metadata alone.

Reconcile acceptance and corrections

For an earlier mutation with an uncertain outcome, retain its operationId and use GET /v1/organizations/{orgId}/operations/{operationId} or MCP operations_get. This read does not retry or finish the operation. A later accepted report revision exposes its recorded acknowledgement metadata. Use the deposit-results read above for the factual unit content. A recorded test-adapter acknowledgement does not establish delivery to a real receiver.

When an acceptance handoff is available to your configured test receiver, a correction can keep its unitRef while changing the assessed condition and variant SKU in a later revision. Treat a handoff revision as an immutable fact, retain the revision you acted on, and reconcile later revisions rather than overwriting history. The current test adapter has providerVerified: false; a synthetic response or report metadata is not actual receiver, provider, carrier, or environment acceptance.

Honor retry guidance

For a whole-request 429 or temporary 503, honor an HTTP Retry-After header when Vault supplies one. It is a delay in seconds. MCP carries the same guidance in _meta.retryAfterSeconds. Retry-After is not permission to replay a mutation: a provider_outcome_unknown response must be observed by its existing operationId, not resubmitted.

Store meta.requestId with a failed or surprising poll for support. Follow the outcomes and errors guide for the current error code vocabulary and the deposit and redemption walkthrough for the separate physical and receiver acceptance boundaries.

Was this page helpful?