> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Order
> Place a single or bulk digital value distribution order
Creates a digital value distribution order. Single and bulk orders use the same endpoint — a single order is simply a bulk order with `quantity: 1`. There is no cart, no temporary state, and no multi-call flow.
Orders are processed asynchronously. The response returns `status: PENDING` — poll `GET /v2/orders/{orderId}` until `status: COMPLETED`, then retrieve codes.
## Endpoint
**POST /v2/orders**
## Headers
| Name | Required | Description |
| ----------------- | ----------- | ----------------------------------------------------------------------------- |
| `Idempotency-Key` | Recommended | UUID for safe retries. Same key + same payload returns the original response. |
## Request Body
| Name | Type | Required | Description |
| ----------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `clientReference` | string | Yes | Your unique reference for this order. Must be unique per account. |
| `currency` | string | Yes | ISO 4217 currency code of the wallet to deduct from (e.g. `USD`, `AED`, `SAR`) |
| `items` | array | Yes | One or more order items |
| `items[].productId` | integer | Yes | Product identifier from `GET /v2/products` |
| `items[].amount` | number | Yes | Face value per unit. Must be within the product's min/max range. |
| `items[].quantity` | integer | Yes | Number of units |
| `items[].itemReference` | string | No | Optional per-item reference for your own tracking |
## Example Request — Single Order
```bash theme={null}
curl -X POST https://partner.orbt.com/v2/orders \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f4d4f3a-b4ec-4ef5-a0ef-c26f71d2f5d8" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-client-id: YOUR_CLIENT_ID" \
-H "x-timestamp: 2026-08-13T10:00:00.000Z" \
-H "x-body-hash: BODY_HASH" \
-H "x-signature: SIGNATURE" \
-d '{
"clientReference": "CLIENT-12346",
"currency": "USD",
"items": [
{ "productId": 1725, "amount": 50, "quantity": 1 }
]
}'
```
## Example Request — Bulk Order
```bash theme={null}
curl -X POST https://partner.orbt.com/v2/orders \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7a9c2d1e-f3b4-4a5c-8d6e-1f2a3b4c5d6e" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-client-id: YOUR_CLIENT_ID" \
-H "x-timestamp: 2026-08-13T10:00:00.000Z" \
-H "x-body-hash: BODY_HASH" \
-H "x-signature: SIGNATURE" \
-d '{
"clientReference": "CLIENT-12345",
"currency": "USD",
"items": [
{ "productId": 1001, "amount": 25, "quantity": 10 },
{ "productId": 1002, "amount": 50, "quantity": 5 }
]
}'
```
```javascript theme={null}
const response = await fetch('https://partner.orbt.com/v2/orders', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Idempotency-Key': '5f4d4f3a-b4ec-4ef5-a0ef-c26f71d2f5d8',
'x-api-key': 'YOUR_API_KEY',
'x-client-id': 'YOUR_CLIENT_ID',
'x-timestamp': timestamp,
'x-body-hash': bodyHash,
'x-signature': signature
},
body: JSON.stringify({
clientReference: 'CLIENT-12345',
currency: 'USD',
items: [
{ productId: 1001, amount: 25, quantity: 10 },
{ productId: 1002, amount: 50, quantity: 5 }
]
})
});
```
## Response — 201 Created
```json theme={null}
{
"data": {
"id": "ORD-123456",
"clientReference": "CLIENT-12345",
"status": "PENDING",
"currency": "USD",
"totalAmount": 500,
"createdAt": "2026-08-13T10:00:00Z"
}
}
```
The order is created in `PENDING` status and processed asynchronously. Poll `GET /v2/orders/{orderId}` to track progress.
## Response — 400 Bad Request
```json theme={null}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"details": [
{ "field": "items[0].amount", "message": "must be greater than 0" }
]
}
}
```
## Response — 402 Insufficient Funds
```json theme={null}
{
"error": {
"code": "BUSINESS_RULE_VIOLATION",
"message": "Insufficient funds in USD wallet"
}
}
```
## Response — 409 Idempotency Conflict
```json theme={null}
{
"error": {
"code": "BUSINESS_RULE_VIOLATION",
"message": "Idempotency key reuse with different request payload"
}
}
```
## Error Responses
| Status | Code | Description |
| ------ | ------------------------- | ------------------------------------------------------ |
| `400` | `VALIDATION_ERROR` | Invalid or missing request body fields |
| `401` | `AUTHENTICATION_ERROR` | Missing or invalid authentication headers |
| `402` | `BUSINESS_RULE_VIOLATION` | Insufficient wallet balance for the requested currency |
| `409` | `BUSINESS_RULE_VIOLATION` | Idempotency key reused with a different payload |
## Create Order Flow
