---
title: Poll deposits and orders
description: Read customer-safe deposit and order facts with checkpoints, revision-aware ingestion, and safe retry handling.
sidebar:
  order: 5.25
---

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.

```json title="example:batch-order-read"
{
  "orderIds": ["order_example_1", "order_example_missing"]
}
```

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

```json title="example:batch-order-result"
{
  "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:

```json title="example:unavailable-batch-order"
{
  "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](/packing-exceptions#find-packing-exceptions-by-polling)
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](/test-orders#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`:

```json title="example:deposit-results"
{
  "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](/reference/purchase-orders/get-deposit-results)
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.

```json title="example:deposit-dispute-events-result"
{
  "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](/reliability) for the current error code
vocabulary and the [deposit and redemption walkthrough](/deposits-and-redemptions)
for the separate physical and receiver acceptance boundaries.
