List Orders

Retrieve orders belonging to the authenticated client. Supports two modes — cursor-based pagination for listing, and direct OID lookup for fetching specific orders.

Retrieve orders associated with your account. The endpoint operates in two mutually exclusive modes depending on whether the oids parameter is present.

Request

Method: GET
Endpoint: /api/v1/orders
Authorization: Bearer <token>

Mode 1: Cursor Pagination

Used when oids is not provided. Returns a sorted, paginated list of orders, newest first.

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. Must be a single value string — repeated params (e.g. `?status=pending&status=processing`) are rejected. See Valid Status Values below.
`type`	`string`	❌	Comma-separated list of order types / providers to filter by. Must be a single value string. 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
`packed`	Order has been packed and is ready for pickup
`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 Requests

GET /api/v1/orders?limit=20&status=pending,processing&type=NORMAL HTTP/1.1
Authorization: Bearer <token>

Fetching the next page using a cursor:

GET /api/v1/orders?limit=20&cursor=2025-06-15T10:00:00.000Z HTTP/1.1
Authorization: Bearer <token>

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 Turuq order identifier
`status`	`string`	Current order status
`source`	`string`	Unified type/provider field (e.g. `NORMAL`, `SHOPIFY`, `OPENAPI`)
`deliveryAttempts`	`number`	Number of delivery attempts made
`customer`	`object`	Customer details
`customer.name`	`string`	Customer's full name
`customer.phone`	`string`	Customer's phone number
`customer.address`	`string`	Customer's street address
`customer.governorate`	`string`	Customer's governorate
`subtotal`	`number`	Order subtotal (EGP)
`shippingFees`	`number`	Shipping fees applied to the order (EGP)
`total`	`number`	Total order value including fees (EGP)
`createdAt`	`string`	ISO 8601 timestamp of when the order was created

Example Response (First Page)

{
  "data": [
    {
      "OID": "0001234567890",
      "status": "pending",
      "source": "NORMAL",
      "deliveryAttempts": 0,
      "customer": {
        "name": "Ahmed Ali",
        "phone": "01012345678",
        "address": "123 Main St",
        "governorate": "Cairo"
      },
      "subtotal": 750.00,
      "shippingFees": 50.00,
      "total": 800.00,
      "createdAt": "2025-06-20T14:23:00.000Z"
    },
    {
      "OID": "0009876543210",
      "status": "processing",
      "source": "SHOPIFY",
      "deliveryAttempts": 0,
      "customer": {
        "name": "Sara Mohamed",
        "phone": "01098765432",
        "address": "456 Nile Corniche",
        "governorate": "Alexandria"
      },
      "subtotal": 1200.00,
      "shippingFees": 65.00,
      "total": 1265.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
  }
}

Mode 2: OID Lookup

Used when the oids query parameter is provided. Fetches one or more specific orders by their numeric order ID. This mode is mutually exclusive with cursor, limit, status, and type.

Query Parameters

Parameter	Type	Required	Description
`oids`	`string`	✅	Comma-separated list of numeric order IDs. Maximum 100 OIDs per request. Must be provided as a single CSV string — repeated params (e.g. `?oids=1&oids=2`) are rejected. OIDs are numeric and do not need to be zero-padded; the API handles formatting internally.

Example Request

GET /api/v1/orders?oids=1234567890,9876543210 HTTP/1.1
Authorization: Bearer <token>

Response — ✅ 200 OK

All requested OIDs were found.

{
  "data": [
    {
      "OID": "0001234567890",
      "status": "delivered",
      "source": "NORMAL",
      "deliveryAttempts": 1,
      "customer": {
        "name": "Ahmed Ali",
        "phone": "01012345678",
        "address": "123 Main St",
        "governorate": "Cairo"
      },
      "subtotal": 750.00,
      "shippingFees": 50.00,
      "total": 800.00,
      "createdAt": "2025-06-20T14:23:00.000Z"
    }
  ],
  "missingOids": []
}

Response — ✅ 206 Partial Content

Some OIDs were found, but others were not (not found or belong to another client).

{
  "data": [
    { "OID": "0001234567890", "status": "delivered", "..." : "..." }
  ],
  "missingOids": ["0009999999999"]
}

Response — ❌ 404 Not Found

None of the requested OIDs matched any orders belonging to the authenticated client.

{
  "error": "No orders found for the requested OIDs."
}

Error Responses

❌ 400 Bad Request

Returned when query parameter validation fails.

OID mode combined with pagination/filter params:

{
  "error": "oids cannot be combined with: cursor, limit"
}

OIDs provided as repeated params instead of CSV:

{
  "error": "oids must be provided as a single comma-separated value."
}

More than 100 OIDs requested:

{
  "error": "A maximum of 100 OIDs can be requested."
}

Non-numeric OID:

{
  "error": "Invalid OID \"abc\": OIDs must be numeric."
}

Invalid cursor value:

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

Status provided as repeated params instead of CSV:

{
  "error": "status must be provided as a single comma-separated value."
}

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