> ## 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 > ### Authorization Requires orders:write. ### Submit decisions Queue 1–50 selected return decisions, including a one-element batch for a single return. Use only actionId/version pairs from a fresh eligibility check. Identical duplicate return operations are deduplicated in first-requested order; conflicting duplicates are rejected. requestId is a UUID idempotency key: retry the same key and unchanged operations after a transport failure. An active matching decision is reused; conflicting active decisions return 409. Returns HTTP 202 with every returnId and jobId. The durable worker rechecks current permissions, store identity, eligibility and version immediately before writing, then verifies the marketplace result. Follow links.poll or GET /api/v1/returns/actions/jobs with every jobIds entry; requires orders:read. data.success is true only when all jobs succeeded, so newly queued work has success=false and pendingCount>0. failed and needs_review are terminal failures; needs_review means the marketplace outcome is uncertain and must be checked before another action. Client disconnection does not cancel queued work. ## OpenAPI ````yaml /openapi.json post /api/v1/returns/actions openapi: 3.1.0 info: title: OmniCommerce API version: 1.0.0 license: name: Proprietary url: https://omnicommerce.sg/terms description: >- OmniCommerce API surface for agents and developer integrations. Includes public endpoints (merchant discovery, product search, compare, catalog, ACO retrieval) and authenticated endpoints (product management via API key Bearer tokens). servers: - url: https://omnicommerce.sg description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: agentic-checkout description: Merchant-fulfilled agentic checkout x-group: Agentic Checkout - name: agents description: agents x-group: Agents - name: analytics description: Sales performance across marketplaces x-group: Analytics - name: aops description: Agent operating procedures x-group: AOPs - name: branding description: branding x-group: Branding - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: commerce description: commerce x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - name: inventory description: Inventory quantities, planning signals, and marketplace listing absence x-group: Inventory - name: looks description: AI-styled product looks x-group: Looks - name: oauth description: OAuth token endpoints x-group: OAuth - name: orders description: Workspace and agentic orders x-group: Orders - name: organizations description: Organization management x-group: Organizations - name: price-books description: Marketplace list-price markup rules x-group: Price Books - name: products description: Product CRUD, bulk import, enrichment, publish, and delist x-group: Products - name: promotions description: Central promotions and marketplace sync x-group: Promotions - name: public-agent description: Public agent discovery and catalog APIs x-group: Public Agent - name: returns description: returns x-group: Returns - name: reviews description: Marketplace product reviews and seller replies x-group: Reviews - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/returns/actions: post: tags: - returns summary: Process Returns description: >- ### Authorization Requires orders:write. ### Submit decisions Queue 1–50 selected return decisions, including a one-element batch for a single return. Use only actionId/version pairs from a fresh eligibility check. Identical duplicate return operations are deduplicated in first-requested order; conflicting duplicates are rejected. requestId is a UUID idempotency key: retry the same key and unchanged operations after a transport failure. An active matching decision is reused; conflicting active decisions return 409. Returns HTTP 202 with every returnId and jobId. The durable worker rechecks current permissions, store identity, eligibility and version immediately before writing, then verifies the marketplace result. Follow links.poll or GET /api/v1/returns/actions/jobs with every jobIds entry; requires orders:read. data.success is true only when all jobs succeeded, so newly queued work has success=false and pendingCount>0. failed and needs_review are terminal failures; needs_review means the marketplace outcome is uncertain and must be checked before another action. Client disconnection does not cancel queued work. operationId: post_v1_returns_actions requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ operations: minItems: 1 maxItems: 50 type: array items: type: object properties: returnId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ actionId: type: string minLength: 1 maxLength: 80 version: type: string pattern: ^[a-f0-9]{64}$ required: - returnId - actionId - version additionalProperties: false organizationId: type: string minLength: 1 maxLength: 120 required: - requestId - operations additionalProperties: false responses: '202': description: >- Decisions queued. Inspect every job; acceptance does not mean success. content: application/json: schema: type: object required: - ok - apiVersion - operationId - status - data - links - warnings - recommendations properties: ok: type: boolean apiVersion: type: string operationId: type: string format: uuid status: type: string enum: - accepted data: type: object properties: correlations: type: array items: type: object properties: kind: type: string const: return_action id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - kind - id success: type: boolean returnIds: type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ jobIds: type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ succeededCount: type: integer minimum: 0 maximum: 9007199254740991 failedCount: type: integer minimum: 0 maximum: 9007199254740991 pendingCount: type: integer minimum: 0 maximum: 9007199254740991 results: type: array items: type: object properties: returnId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ jobId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ success: type: boolean status: type: string enum: - queued - running - submitting - succeeded - failed - needs_review evidence: anyOf: - type: object properties: accepted: type: boolean verified: type: boolean statusBefore: anyOf: - type: string - type: 'null' statusAfter: anyOf: - type: string - type: 'null' - type: 'null' error: anyOf: - type: string - type: 'null' required: - returnId - jobId - success - status - evidence - error required: - correlations - success - returnIds - jobIds - succeededCount - failedCount - pendingCount - results links: type: object additionalProperties: type: string warnings: type: array items: type: string recommendations: type: array items: type: string '400': description: >- Invalid request, conflicting operations, singular arguments or a batch exceeding the endpoint limit. '401': description: Missing or invalid credentials. '403': description: >- Missing scope, organization mismatch, or a target outside the caller's assigned stores and markets. '409': description: >- A conflicting decision is active or requestId was already used for a different operation. '429': description: Rate limit exceeded. '503': description: >- Service unavailable. Retry a submission with the same requestId and unchanged operations. security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Bearer API key for server-to-server access. Session auth is also supported in first-party UI flows. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.