> ## 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.

# Process returns

> Review and submit marketplace return decisions for one return or a batch.

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

| Operation | Scope |
| - | - |
| List or retrieve return records | `returns:read` |
| Check available decisions and submit them | `orders:write` |
| Check processing jobs | `orders:read` |

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](https://docs.omnicommerce.ai/webhooks/returns.md). 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

```http theme={null}
GET /api/v1/returns/actions?returnIds=11111111-1111-4111-8111-111111111111&returnIds=22222222-2222-4222-8222-222222222222
```

`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`:

```json theme={null}
{
  "requestId": "33333333-3333-4333-8333-333333333333",
  "operations": [
    {
      "returnId": "11111111-1111-4111-8111-111111111111",
      "actionId": "ACTION_ID_FROM_THE_CHECK",
      "version": "VERSION_FROM_THE_CHECK"
    }
  ]
}
```

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](https://docs.omnicommerce.ai/guides/commerce-verification.md). 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:

```http theme={null}
GET /api/v1/returns/actions/jobs?jobIds=JOB_UUID_1&jobIds=JOB_UUID_2
```

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.

| Job status | Meaning |
| - | - |
| `queued`, `running`, `submitting` | Processing or verification is pending. |
| `succeeded` | The selected decision was submitted and its marketplace result verified. |
| `failed` | The decision failed; inspect `error`. |
| `needs_review` | The marketplace outcome is uncertain or verification did not complete. Check the return before submitting another decision. |

`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](https://docs.omnicommerce.ai/sdk/typescript.md#return-processing) and [Python SDK](https://docs.omnicommerce.ai/sdk/python.md#return-processing) expose this same flow.


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