Skip to main content
Use the same two operations across marketplace catalog writes, fulfillment and returns: 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:
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:
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:
Python SDK 0.14.0, with the same methods on AsyncOmni:
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.