> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce jobs and verification

> Wait for catalog, order and return operations, then verify marketplace state.

Use the same two operations across marketplace catalog writes, fulfillment and returns:

| Operation | API | Agent tool |
| - | - | - |
| Wait for completion | `POST /api/v1/commerce/jobs/await` | `await_commerce_jobs` |
| Verify marketplace state | `POST /api/v1/commerce/state/verify` | `verify_commerce_state` |

Both calls are reads. They never resubmit an operation. Catalog targets require `catalog:read`; order and return targets require `orders:read`. A mixed batch requires both. API keys resolve organization scope from the credential; session callers include `organizationId`. Current organization and store permissions apply to every fulfillment target.

## Wait for every job

Order and return submissions return `data.correlations`. Pass all of them together, including correlations from multiple submissions:

```json theme={null}
{
  "correlations": [
    { "kind": "order_action", "id": "11111111-1111-4111-8111-111111111111" },
    { "kind": "return_action", "id": "22222222-2222-4222-8222-222222222222" }
  ],
  "timeoutMs": 30000
}
```

The waiter supports `inventory_job`, `price_event`, `price_book_sync`, `publish_job`, `delist_batch`, `store_switch`, `omni_delete`, `zalora_import`, `enrichment_batch`, `order_action`, and `return_action`. Use correlations returned by the operation; do not reinterpret unrelated workflow or event IDs as job IDs. Future scheduled operations must execute before their marketplace effects can be checked.

The maximum is 50,000 correlations. IDs are trimmed and duplicate kind/ID pairs collapse in first-requested order. `timeoutMs` defaults to zero for one status read and supports up to 120,000 milliseconds. Pending work continues durably after a timeout; repeat the read with the same correlations.

Inspect `data.jobs`, `pendingCount`, `succeededCount`, and `failedCount`. Each job retains its target identities and error evidence. Successful label jobs expose `labels[]` URLs. A missing or inaccessible fulfillment job is an explicit failure. A return job's `sourceStatus: "needs_review"` remains an uncertain terminal outcome; never automatically resubmit it.

`data.success` reports job completion. Verify marketplace state before reporting that the requested operation took effect.

## Verify the selected operation

For order and return operations, send their correlations to `/api/v1/commerce/state/verify` without `timeoutMs`:

```json theme={null}
{
  "correlations": [
    { "kind": "order_action", "id": "11111111-1111-4111-8111-111111111111" },
    { "kind": "return_action", "id": "22222222-2222-4222-8222-222222222222" }
  ]
}
```

Verification reads the current marketplace state through the shared adapters and compares it with the stored operation. It checks exact organization, store and external order/return identities. One verified return decision may leave later lifecycle steps outstanding. Label verification establishes generated files, not physical printing.

Unsupported provider reads, missing records, connection failures, unchanged state and uncertain evidence produce unsuccessful per-target checks. Providers that omit tracking from order reads cannot establish a tracking update from an acknowledgement alone. WhatsApp has no marketplace fulfillment API; Amazon and WhatsApp return processing limitations remain explicit.

For products, provide `productIds` plus a shared `expected`, or `targets: [{productId, expected}]` for different values. Use each successful write's `commerceReceipt.expected`, including currency for monetary expectations. Product targets can accompany order/return correlations in one request. Product outcomes are in `results[]`; fulfillment outcomes are in `jobs[]`. Aggregate success requires every requested check to succeed.

## Price-book sync

`sync_product_price` with `all=true` returns a `price_book_sync` correlation. Await it, then send the same correlation to state verification. The server checks every exact listing/store against the prices and currencies acknowledged by that batch. Failed, skipped, missing and unconfirmed targets remain explicit; later catalog or price-book changes do not replace the original expectations.

Agent tool product arguments are flat: use `productIds` with shared `price`, `currency`, `quantity` or `listingStatus`, or `targets: [{productId, price, currency}]` for differing values. The v1 API and SDK retain the `expected` object shown above.

## SDKs

TypeScript SDK 0.19.0:

```ts theme={null}
const correlations = submitted.data.correlations;
const progress = await client.commerce.awaitJobs({
  correlations,
  timeoutMs: 30000,
});
const state = await client.commerce.verifyState({ correlations });
```

Python SDK 0.14.0, with the same methods on `AsyncOmni`:

```python theme={null}
correlations = submitted["data"]["correlations"]
progress = client.commerce.await_jobs(correlations=correlations, timeout_ms=30000)
state = client.commerce.verify_state(correlations=correlations)
```

The resource-specific public job lookup endpoints remain available for existing integrations. Agents use the common waiter and verifier; the separate `get_order_action_jobs` and `get_return_action_jobs` agent tools have been removed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.