> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt > Use this file to discover all available pages before exploring further. # List Orders > List orders for the authenticated organization using the same filters, sorting, and pagination semantics as the workspace Orders listing page. Requires `orders:read`. ## OpenAPI ````yaml /openapi.json get /api/v1/orders 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: commerce description: Root commerce discovery x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - 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, and publish 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: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/orders: get: tags: - orders summary: List Orders description: >- List orders for the authenticated organization using the same filters, sorting, and pagination semantics as the workspace Orders listing page. Requires `orders:read`. operationId: get_v1_orders parameters: - name: organizationId in: query required: false description: >- Optional organization scope for session-authenticated calls. OAuth client credentials resolve the organization from the token. schema: type: string maxLength: 120 - name: q in: query required: false description: >- Search order number, external order ID, buyer fields, and line-item product/SKU fields. schema: type: string maxLength: 140 - name: status in: query required: false description: Filter by normalized order status group. schema: type: string enum: - to_ship - shipped - completed - pending - return - canceled - name: marketplace in: query required: false description: >- Comma-separated marketplace platforms (for example `shopee,lazada,tiktok,zalora`). schema: type: string maxLength: 200 - name: country in: query required: false description: Comma-separated normalized country codes. schema: type: string maxLength: 200 - name: store in: query required: false description: Comma-separated marketplace account IDs. schema: type: string maxLength: 400 - name: sortBy in: query required: false description: >- Comma-separated sort tokens. Supports multi-sort up to six tokens. Aliases: `latest` -> `updated_desc`, `oldest` -> `updated_asc`. schema: type: string maxLength: 240 - name: dateFrom in: query required: false description: Inclusive lower bound on order created date (`YYYY-MM-DD`). schema: type: string format: date - name: dateTo in: query required: false description: Inclusive upper bound on order created date (`YYYY-MM-DD`). schema: type: string format: date - name: limit in: query required: false description: >- Result limit per page. Values above 50 are clamped silently. Defaults to 20. schema: type: integer minimum: 1 maximum: 50 default: 20 - name: offset in: query required: false description: >- Zero-based pagination offset. Use `pagination.nextOffset` from the previous response to page forward. schema: type: integer minimum: 0 default: 0 responses: '200': description: Orders page returned. content: application/json: schema: type: object properties: items: type: array items: type: object properties: paymentReceived: type: - number - 'null' description: >- Formula-net marketplace payment. Null until every active line has been reconciled. orderCogs: type: - number - 'null' description: >- Order-time COGS total. Null while any active line lacks a cost snapshot. orderProfit: type: - number - 'null' orderMargin: type: - number - 'null' hasReturnSignal: type: boolean returnRefundAmount: type: number minimum: 0 returnState: type: string enum: - none - partial - full includeInSalesMetrics: type: boolean hasMore: type: boolean nextOffset: type: integer summary: type: object properties: totalCount: type: integer toShipCount: type: integer shippedCount: type: integer completedCount: type: integer pendingCount: type: integer returnCount: type: integer canceledCount: type: integer pagination: type: object properties: offset: type: integer limit: type: integer total: type: integer hasMore: type: boolean nextOffset: type: - integer - 'null' maxLimit: type: integer defaultLimit: type: integer '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden or missing `orders:read` scope '429': description: Rate limit exceeded '500': description: Internal Server Error 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. ````