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.