# List orders

> Returns a list of orders.

Breadcrumb: API › List orders
Docs index: https://docs.cevoid.com/developers/llms.txt

`GET https://api.cevoid.com/v2/orders`

Returns a list of orders.

## Authorizations

Bearer token in the Authorization header: `Authorization: Bearer <key>` (API key).

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | `string` | No | Opaque cursor returned from a previous list response Example: `eyJpZCI6InBvc3RfMDEifQ`. |
| `limit` | `integer` | No | Page size between 1 and 100 Range: `1 <= x <= 100`. Example: `25`. |
| `query` | `string` | No | Search by order number, source order identifier, or buyer email. Length: `1 to 255`. Example: `#1001`. |
| `source_type` | `enum<string>` | No | Filter by source system. Allowed values: `SHOPIFY`, `WOOCOMMERCE`, `MYSTORE`, `NORDISK_EHANDEL`, `VISKAN`, `CENTRA`, `PUBLIC_API`, `OTHER`. Example: `PUBLIC_API`. |
| `source_connection_id` | `string` | No | Filter by the exact source namespace supplied when the order was created. Length: `1 to 255`. Example: `erp-production`. |
| `market_id` | `string` | No | Filter by Cevoid market ID. Example: `mar_us`. |
| `fulfillment_status` | `enum<string>` | No | Filter by current fulfillment state. Allowed values: `PENDING`, `PARTIALLY_FULFILLED`, `FULFILLED`, `DELIVERED`. Example: `PENDING`. |
| `financial_status` | `enum<string>` | No | Filter by current payment state. Allowed values: `PENDING`, `PAID`, `PARTIALLY_REFUNDED`, `REFUNDED`. Example: `PAID`. |
| `product_id` | `string` | No | Filter by an exact source product identifier on any active order line. Length: `1 to 255`. Example: `product_123`. |
| `placed_from` | `string<date-time>` | No | Inclusive lower bound for placed_at. Example: `2026-07-01T00:00:00.000Z`. |
| `placed_to` | `string<date-time>` | No | Inclusive upper bound for placed_at. Example: `2026-07-31T23:59:59.999Z`. |
| `fulfilled_from` | `string<date-time>` | No | Inclusive lower bound for fulfilled_at. Example: `2026-07-01T00:00:00.000Z`. |
| `fulfilled_to` | `string<date-time>` | No | Inclusive upper bound for fulfilled_at. Example: `2026-07-31T23:59:59.999Z`. |
| `delivered_from` | `string<date-time>` | No | Inclusive lower bound for delivered_at. Example: `2026-07-01T00:00:00.000Z`. |
| `delivered_to` | `string<date-time>` | No | Inclusive upper bound for delivered_at. Example: `2026-07-31T23:59:59.999Z`. |

## Response

### 200: Successful response

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | Yes | Items returned for this page. |
| `data[].id` | `string` | Yes | Cevoid order ID. Example: `ord_abc123`. |
| `data[].ingestion_mode` | `enum<string>` | No | Processing mode of the latest order write. Historical mode suppresses automatic Flows. Live mode allows new lifecycle transitions to trigger Flows. Absent for orders without a live or historical mode. Allowed values: `live`, `historical`. Example: `live`. |
| `data[].source` | `object` | Yes |  |
| `data[].source.type` | `enum<string>` | No | System that owns this order. Absent when the order has no connected source. Allowed values: `SHOPIFY`, `WOOCOMMERCE`, `MYSTORE`, `NORDISK_EHANDEL`, `VISKAN`, `CENTRA`, `PUBLIC_API`, `OTHER`. Example: `PUBLIC_API`. |
| `data[].source.connection_id` | `string` | No | Stable source namespace for the order. Absent when the order has no connected source. Example: `erp-production`. |
| `data[].source.external_order_id` | `string` | Yes | Order identifier in the source system. Example: `order_123`. |
| `data[].order_number` | `string` | No | Customer-facing order number. Example: `#1001`. |
| `data[].buyer` | `object` | No | Buyer identity. Absent when the order carries no buyer information. |
| `data[].buyer.email` | `string` | No | Buyer email as supplied by the source system. Example: `buyer@example.com`. |
| `data[].buyer.external_customer_id` | `string` | No | Customer identifier in the source system. Example: `customer_123`. |
| `data[].buyer.profile_id` | `string` | No | Cevoid profile ID. Absent when no profile is linked to the order. Example: `prf_sarah`. |
| `data[].placed_at` | `string<date-time>` | Yes | ISO 8601 timestamp when the order was placed. Example: `2026-07-24T09:00:00.000Z`. |
| `data[].currency` | `string` | Yes | Three-letter uppercase ISO currency code. Example: `USD`. |
| `data[].money` | `object` | Yes |  |
| `data[].money.total` | `number` | Yes | Current declared order total. Example: `55`. |
| `data[].money.sub_total` | `number` | Yes | Current merchandise subtotal. Example: `50`. |
| `data[].money.discount` | `number` | No | Current order-level discount total. Example: `5`. |
| `data[].money.tax` | `number` | No | Current order-level tax total. Example: `5`. |
| `data[].money.shipping` | `number` | No | Current order-level shipping total. Example: `5`. |
| `data[].money.refunded` | `number` | No | Cumulative refunded amount. Example: `0`. |
| `data[].fulfillment_status` | `enum<string>` | Yes | Current order fulfillment state. Allowed values: `PENDING`, `PARTIALLY_FULFILLED`, `FULFILLED`, `DELIVERED`. Example: `PENDING`. |
| `data[].financial_status` | `enum<string>` | Yes | Current order payment state. Allowed values: `PENDING`, `PAID`, `PARTIALLY_REFUNDED`, `REFUNDED`. Example: `PAID`. |
| `data[].fulfilled_at` | `string<date-time>` | No | ISO 8601 timestamp when the order was fulfilled. Example: `2026-07-25T10:00:00.000Z`. |
| `data[].delivered_at` | `string<date-time>` | No | ISO 8601 timestamp when the order was delivered. Example: `2026-07-26T14:00:00.000Z`. |
| `data[].cancelled` | `boolean` | Yes | Whether the order is cancelled. Example: `false`. |
| `data[].cancelled_at` | `string<date-time>` | No | ISO 8601 timestamp when the order was cancelled. Example: `2026-07-24T10:00:00.000Z`. |
| `data[].paid_at` | `string<date-time>` | No | ISO 8601 timestamp when the order was paid. Example: `2026-07-24T09:00:01.000Z`. |
| `data[].last_refunded_at` | `string<date-time>` | No | ISO 8601 timestamp of the most recent refund. Example: `2026-07-28T11:00:00.000Z`. |
| `data[].market_id` | `string` | No | Cevoid market ID. Example: `mar_us`. |
| `data[].lines` | `object[]` | Yes |  |
| `data[].lines[].external_line_id` | `string` | Yes | Stable line identifier within the source order. Example: `line_1`. |
| `data[].lines[].product_id` | `string` | No | Product identifier in the source catalog. Absent when the line names no product. Example: `product_123`. |
| `data[].lines[].variant_id` | `string` | No | Variant identifier in the source catalog. Example: `variant_456`. |
| `data[].lines[].sku` | `string` | No | Merchant SKU snapshot. Example: `TSHIRT-BLACK-M`. |
| `data[].lines[].quantity` | `integer` | Yes | Absolute ordered quantity. Range: `0 <= x`. Example: `1`. |
| `data[].lines[].unit_price` | `number` | Yes | Price per unit in the order currency. Example: `50`. |
| `data[].lines[].discount` | `number` | No | Discount allocated to this line. Example: `0`. |
| `data[].lines[].refund` | `number` | No | Cumulative amount refunded for this line. Example: `0`. |
| `data[].lines[].returned_units` | `integer` | No | Absolute number of returned units. Range: `0 <= x`. Example: `0`. |
| `data[].lines[].fulfillment_status` | `enum<string>` | Yes | Current fulfillment state for this line. Allowed values: `PENDING`, `PARTIALLY_FULFILLED`, `FULFILLED`, `DELIVERED`. Example: `PENDING`. |
| `data[].lines[].delivered_at` | `string<date-time>` | No | ISO 8601 timestamp when this line was delivered. Example: `2026-07-26T14:00:00.000Z`. |
| `data[].lines[].removed_at` | `string<date-time>` | No | Time the line was removed from the order. Example: `2026-07-27T14:00:00.000Z`. |
| `data[].created_at` | `string<date-time>` | Yes | ISO 8601 timestamp when Cevoid created the order. Example: `2026-07-24T09:00:01.000Z`. |
| `data[].updated_at` | `string<date-time>` | Yes | ISO 8601 timestamp when Cevoid last updated the order. Example: `2026-07-24T09:00:01.000Z`. |
| `data[].removed_at` | `string<date-time>` | No | Time the order was deleted. Example: `2026-08-01T09:00:00.000Z`. |
| `has_more` | `boolean` | Yes | Whether another page of results is available. Example: `true`. |
| `next_cursor` | `string \| null` | Yes | Opaque cursor to request the next page, or null when the list is exhausted. Example: `eyJpZCI6InJlc291cmNlXzI1In0`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |

```json
{
  "data": [
    {
      "id": "ord_abc123",
      "ingestion_mode": "live",
      "source": {
        "type": "PUBLIC_API",
        "connection_id": "erp-production",
        "external_order_id": "order_123"
      },
      "order_number": "#1001",
      "buyer": {
        "email": "buyer@example.com",
        "external_customer_id": "customer_123",
        "profile_id": "prf_sarah"
      },
      "placed_at": "2026-07-24T09:00:00.000Z",
      "currency": "USD",
      "money": {
        "sub_total": 50,
        "discount": 5,
        "tax": 5,
        "shipping": 5,
        "total": 55,
        "refunded": 0
      },
      "fulfillment_status": "PENDING",
      "financial_status": "PAID",
      "paid_at": "2026-07-24T09:00:01.000Z",
      "cancelled": false,
      "market_id": "mar_us",
      "lines": [
        {
          "external_line_id": "line_1",
          "product_id": "product_123",
          "variant_id": "variant_456",
          "sku": "TSHIRT-BLACK-M",
          "quantity": 1,
          "unit_price": 50,
          "discount": 0,
          "refund": 0,
          "returned_units": 0,
          "fulfillment_status": "PENDING"
        }
      ],
      "created_at": "2026-07-24T09:00:01.000Z",
      "updated_at": "2026-07-24T09:00:01.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Im9yZF9hYmMxMjMifQ"
}
```

### 401: Unauthorized

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | No | Optional machine-readable error details. |
| `additional_data.{key}` | `any` | No |  |
| `status` | `number` | Yes | HTTP status code for the error response. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable description of the error. Example: `Route not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers: the same as 200.

```json
{
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "request_id": "req_abc123"
}
```

### 403: Forbidden

`application/json`

Same fields as 401.

Response headers: the same as 200.

```json
{
  "status": 403,
  "code": "forbidden",
  "message": "Forbidden",
  "request_id": "req_abc123"
}
```

### 422: Validation error

`application/json`

Same fields as 401.

Response headers: the same as 200.

```json
{
  "additional_data": {
    "errors": [
      {
        "field": "query.market",
        "message": "Invalid input: expected string, received array"
      }
    ]
  },
  "status": 422,
  "code": "validation_error",
  "message": "Validation error",
  "request_id": "req_abc123"
}
```

### 429: Too many requests

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_data` | `object` | Yes | Machine-readable rate-limit details. |
| `additional_data.retry_after_seconds` | `integer` | Yes | Range: `0 <= x`. |
| `additional_data.{key}` | `any` | No |  |
| `status` | `integer` | Yes | HTTP status code. Example: `404`. |
| `code` | `string` | Yes | Stable machine-readable error code. Example: `not_found`. |
| `message` | `string` | Yes | Human-readable error description. Example: `Resource not found`. |
| `request_id` | `string` | No | Request identifier for support and tracing. Example: `req_abc123`. |

Response headers:

| Header | Type | Description |
| --- | --- | --- |
| `Cevoid-Processing-Ms` | `string` | End-to-end request processing time in milliseconds |
| `Cevoid-Request-Id` | `string` | Request identifier for support and tracing |
| `RateLimit-Limit` | `string` | Current rate limit bucket size |
| `RateLimit-Remaining` | `string` | Remaining requests in the current rate limit window |
| `RateLimit-Reset` | `integer` | Seconds until the next request token is available |
| `Retry-After` | `integer` | Seconds to wait before retrying the request |

```json
{
  "status": 429,
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded",
  "request_id": "req_abc123",
  "additional_data": {
    "retry_after_seconds": 1
  }
}
```

### 500: Internal server error

`application/json`

Same fields as 401.

Response headers: the same as 200.

```json
{
  "status": 500,
  "code": "internal_server_error",
  "message": "Internal server error",
  "request_id": "req_abc123"
}
```

## Request example

```bash
curl 'https://api.cevoid.com/v2/orders' \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

---

Canonical: https://docs.cevoid.com/developers/api/orders/list-orders