Create 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

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

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 }
    ]
  }'

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

{
  "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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "items[0].amount", "message": "must be greater than 0" }
    ]
  }
}

Response — 402 Insufficient Funds

{
  "error": {
    "code": "BUSINESS_RULE_VIOLATION",
    "message": "Insufficient funds in USD wallet"
  }
}

Response — 409 Idempotency Conflict

{
  "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

Orbt API Order Fulfillment 2026 08 13 091917

Create Order Flow

Orbt API Order Fulfillment 2026 08 13 092031

Get Started

Platform

API

Use Cases

Create Order

Endpoint

Headers

Request Body

Example Request — Single Order

Example Request — Bulk Order

Response — 201 Created

Response — 400 Bad Request

Response — 402 Insufficient Funds

Response — 409 Idempotency Conflict

Error Responses

Create Order Flow

​Endpoint

​Headers

​Request Body

​Example Request — Single Order

​Example Request — Bulk Order

​Response — 201 Created

​Response — 400 Bad Request

​Response — 402 Insufficient Funds

​Response — 409 Idempotency Conflict

​Error Responses

​Create Order Flow

Endpoint

Headers

Request Body

Example Request — Single Order

Example Request — Bulk Order

Response — 201 Created

Response — 400 Bad Request

Response — 402 Insufficient Funds

Response — 409 Idempotency Conflict

Error Responses

Create Order Flow