Skip to main content
Submit a single return or a batch with one POST /api/v1/returns/actions call. The server executes and verifies the decisions in the background. A submission processes the selected decision at the return’s current stage; it does not automatically approve a request, confirm physical receipt, and refund the buyer in one step. Approving a return request and refunding without requiring the item back have different effects. Check the marketplace’s current choices, review the intended decision, then submit it. The same eligibility and status rules power the Orders page.

​
Permissions

API keys supply organization scope. Session callers include organizationId. Every return and its order must belong to the authenticated organization and the caller’s assigned stores and markets.

​
1. Find the return requests

Use GET /api/v1/returns with marketplace, accountId, and externalOrderId filters, or consume return webhooks. Target the OmniCommerce return UUID, not the marketplace return number or order UUID. For an exact order selection, use GET /api/v1/returns/orders?orderIds=ORDER_UUID_1&orderIds=ORDER_UUID_2 (orders:read). It returns every distinct return request per order, including history, with a returnId to pass to the live check. Its processingEligible flag is a saved candidate indicator; it does not replace live eligibility. An order can have several distinct return requests, including an older cancelled request and a newer active request. History remains readable; completed and cancelled requests do not offer processing decisions.

​
2. Check the current decisions

data.results contains one entry per return in first-requested order. A successful check provides actions with an id, label, and description, plus a version for the reviewed state. Submit only a choice returned for that return. There is no universal action ID across marketplaces or stages. An empty actions array means no seller decision is currently available. Inspect limitation for unsupported operations. Amazon and WhatsApp currently expose explicit processing limitations. Shopee, Lazada, TikTok, Shopify, Zalora, and eBay expose the decisions their adapters support for the current provider state. Shopify refund-only history records cannot be processed as return requests. One store’s connection failure appears as success: false and error for its return; other checks continue. Batch success indicates every eligibility check succeeded, not that every return has an available decision. The response excludes buyer remarks, shipping evidence, and raw marketplace payloads.

​
3. Submit the reviewed decisions

Send this body to POST /api/v1/returns/actions:
Use one operation for a single return, or up to 50 for a batch. Copy version unchanged from the check. Review the action’s effect before submitting, especially refund decisions. The response is 202 with every returnId and jobId in data, and a links.poll URL containing all job IDs. Acceptance means the decisions were queued. Newly queued jobs have data.success: false and pendingCount above zero. Reuse the same UUID requestId and unchanged operations after a network failure. Identical duplicate operations are deduplicated in first-requested order; conflicting operations for the same return are rejected. A conflicting active decision or reuse of a request key for a different operation returns 409. All requests allow 1–50 input entries before deduplication. Immediately before writing, the worker rechecks current permissions, store identity, marketplace eligibility, and the reviewed version. A changed return fails explicitly. Fetch new choices and review the decision again.

​
4. Wait and verify

Pass all returned data.correlations to the shared commerce waiter and state verifier. The same flow supports mixed catalog, order and return work. Existing integrations can continue to use the lookup below.

​
Resource-specific job lookup

Follow links.poll or call:
Use every returned job ID. The lookup reads current state once; repeat with backoff while pendingCount is above zero. A client timeout does not cancel queued work. failedCount includes needs_review. data.success is true only when every requested job succeeded. The envelope’s status: "completed" means the lookup finished. Successful execution of one decision does not imply the entire buyer return lifecycle is complete. The TypeScript SDK and Python SDK expose this same flow.