> ## 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. # Check Return Actions > ### Authorization Requires orders:write. ### Eligibility Read live marketplace decisions for 1–50 OmniCommerce return UUIDs using repeated returnIds query parameters. Refreshes the saved return state through the same service as the order UI. All targets are organization- and store-scoped before marketplace access. Results preserve first-requested order; one provider failure does not block another store. data.success describes eligibility checks, not whether an action is available. Completed, cancelled and other terminal returns have no actions. Check actions.length and limitation; never infer eligibility from status alone. Amazon and WhatsApp currently return explicit processing limitations. Other marketplaces expose only decisions supported by their current API state. No buyer remarks, shipping evidence or raw provider payloads are returned. Pass each chosen action id and version unchanged to POST /api/v1/returns/actions. ## OpenAPI ````yaml /openapi.json get /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: get: tags: - returns summary: Check Return Actions description: >- ### Authorization Requires orders:write. ### Eligibility Read live marketplace decisions for 1–50 OmniCommerce return UUIDs using repeated returnIds query parameters. Refreshes the saved return state through the same service as the order UI. All targets are organization- and store-scoped before marketplace access. Results preserve first-requested order; one provider failure does not block another store. data.success describes eligibility checks, not whether an action is available. Completed, cancelled and other terminal returns have no actions. Check actions.length and limitation; never infer eligibility from status alone. Amazon and WhatsApp currently return explicit processing limitations. Other marketplaces expose only decisions supported by their current API state. No buyer remarks, shipping evidence or raw provider payloads are returned. Pass each chosen action id and version unchanged to POST /api/v1/returns/actions. operationId: get_v1_returns_actions parameters: - name: returnIds in: query required: true description: >- Repeat this query parameter for each UUID. Between 1 and 50 entries, deduplicated in first-requested order. style: form explode: true schema: minItems: 1 maxItems: 50 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)$ - name: organizationId in: query required: false description: >- Session callers only. API keys resolve organization scope from the credential. style: form explode: true schema: type: string minLength: 1 maxLength: 120 responses: '200': description: >- Request completed. Inspect data.success, per-target results and pendingCount for processing progress. 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: - completed data: type: object properties: 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)$ succeededCount: type: integer minimum: 0 maximum: 9007199254740991 failedCount: type: integer minimum: 0 maximum: 9007199254740991 results: type: array items: anyOf: - 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)$ success: type: boolean const: true marketplace: type: string enum: - shopee - lazada - tiktok - shopify - whatsapp - zalora - amazon - ebay marketplaceStatus: anyOf: - type: string - type: 'null' externalReturnId: type: string externalOrderId: anyOf: - type: string - type: 'null' actions: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label - description limitation: type: string version: type: string required: - returnId - success - marketplace - marketplaceStatus - externalReturnId - externalOrderId - actions - version - 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)$ success: type: boolean const: false error: type: string required: - returnId - success - error required: - success - returnIds - succeededCount - failedCount - 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. '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.