List Orders

Retrieve a paginated list of orders belonging to the authenticated client, across both standard and integration order collections.

Retrieve a cursor-paginated list of orders associated with your account. Results are sorted newest-first and aggregate across both the standard order and integration order collections.

Request

Method: GET
Endpoint: /api/v1/orders
Content-Type: N/A (query parameters only)

Query Parameters

Parameter	Type	Required	Description
`limit`	`number`	❌	Number of orders to return per page. Min `1`, max `100`. Defaults to `20`.
`cursor`	`string`	❌	ISO 8601 date string used for cursor-based pagination. Pass the `nextCursor` value from the previous response to retrieve the following page. Omit on the first request.
`status`	`string`	❌	Comma-separated list of order statuses to filter by. See Valid Status Values below.
`type`	`string`	❌	Comma-separated list of order types / providers to filter by. See Valid Type Values below.

Valid Status Values

Value	Description
`pending`	Order has been created and is awaiting processing
`processing`	Order is being prepared for dispatch
`pickedUp`	Order has been picked up by the courier
`outForDelivery`	Order is out for delivery
`delivered`	Order has been delivered to the customer
`collected`	Payment for the order has been collected
`returned`	Order was returned to the warehouse
`cancelled`	Order was cancelled
`postponed`	Delivery has been postponed
`unreachable`	Customer could not be reached
`outOfStock`	One or more products were out of stock
`invalidAddress`	Customer address could not be validated
`RTW`	Return to warehouse in progress
`QC`	Order is undergoing quality control

Valid Type Values

Standard order types:

Value	Description
`NORMAL`	A standard fulfillment order
`PROMOTIONAL`	A promotional / gifting order
`EXCHANGE`	An exchange order
`REFUND`	A refund/return order

Integration order providers:

Value	Description
`SHOPIFY`	Order originated from a Shopify store
`WOOCOMMERCE`	Order originated from a WooCommerce store
`OPENAPI`	Order created via the Open API

Example Request

GET /api/v1/orders?limit=20&status=pending,processing&type=NORMAL HTTP/1.1
X-API-Key: your-api-key

Fetching the next page using a cursor:

GET /api/v1/orders?limit=20&cursor=2025-06-15T10:00:00.000Z HTTP/1.1
X-API-Key: your-api-key

Response

✅ 200 OK

Orders were successfully retrieved.

Response Body

Field	Type	Description
`data`	`array`	Array of order objects for the current page
`pagination`	`object`	Pagination metadata
`pagination.limit`	`number`	The effective page size used
`pagination.hasNextPage`	`boolean`	`true` if more results are available after this page
`pagination.nextCursor`	`string \| null`	ISO 8601 date string to pass as `cursor` on the next request. `null` when on the last page.

Order Object Fields

Field	Type	Description
`OID`	`string`	Unique 13-digit Turuq order identifier
`status`	`string`	Current order status
`source`	`string`	Unified type/provider field (e.g. `NORMAL`, `SHOPIFY`, `OPENAPI`)
`customerName`	`string`	Customer's full name
`customer.governorate`	`string`	Customer's governorate
`subtotal`	`number`	Order subtotal (EGP)
`total`	`number`	Total order value including fees (EGP)
`shippingFees`	`number`	Shipping fees applied to the order (EGP)
`createdAt`	`string`	ISO 8601 timestamp of when the order was created

Example Response (First Page)

{
  "data": [
    {
      "OID": "0001234567890",
      "status": "pending",
      "source": "NORMAL",
      "customerName": "Ahmed Ali",
      "customer": {
        "governorate": "Cairo"
      },
      "subtotal": 750.00,
      "total": 800.00,
      "shippingFees": 50.00,
      "createdAt": "2025-06-20T14:23:00.000Z"
    },
    {
      "OID": "0009876543210",
      "status": "processing",
      "source": "SHOPIFY",
      "customerName": "Sara Mohamed",
      "customer": {
        "governorate": "Alexandria"
      },
      "subtotal": 1200.00,
      "total": 1265.00,
      "shippingFees": 65.00,
      "createdAt": "2025-06-18T09:10:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasNextPage": true,
    "nextCursor": "2025-06-18T09:10:00.000Z"
  }
}

Example Response (Last Page)

{
  "data": [ /* ... */ ],
  "pagination": {
    "limit": 20,
    "hasNextPage": false,
    "nextCursor": null
  }
}

❌ 400 Bad Request

Returned when query parameter validation fails.

Invalid cursor value:

{
  "error": "Invalid cursor value. Must be a valid ISO 8601 date string."
}

Invalid status value:

{
  "error": "Invalid status value(s): invalidStatus"
}

Invalid type value:

{
  "error": "Invalid type value(s): UNKNOWN_PROVIDER"
}

❌ 500 Internal Server Error

{
  "error": "Internal Server Error"
}

This endpoint uses cursor-based pagination for efficient traversal of large result sets. Unlike offset-based pagination, cursors are stable across concurrent writes and do not degrade in performance as you navigate deeper into the dataset.

First request — omit cursor. The response will contain the first limit results.
Subsequent requests — pass the nextCursor value from the previous response as the cursor parameter.
End of results — when hasNextPage is false and nextCursor is null, you have retrieved all matching orders.

The cursor value is an ISO 8601 timestamp. Results with a createdAt strictly before the cursor are returned, ensuring no page overlap.

For an overview of all order-related endpoints, visit the Orders Overview.

On this page