---
title: "Create order"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.cardzone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create order

Path: Cardzone B2B API › Orders

`POST /api/b2b/v1/orders`

Requires an active API credential with the `orders:create` permission. Send the complete recipient object advertised by the catalog. A missing Mobile Legends zone_id returns 422 validation_failed with error.details.recipient including 'is missing zone_id'; no order or fulfillment is created. The live examples use illustrative UUIDs: replace product_id with the top-level id returned by your live catalog. With a sandbox credential, `product_id` selects the static response scenario. Unknown non-blank sandbox product IDs default to the success response.

## Authentication

- `BearerAuth`, http, header `Authorization`

## Request body

_Required._

- `product_id` (`createOrder.product_id`; string, required) — Sellable variant UUID: use the id returned by the products endpoint. For sandbox keys, this selects the static response scenario: - `018f0000-0000-7000-8000-000000000001` (`sandbox-success-voucher`): Static sandbox product that returns a fulfilled voucher order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPE`. - `018f0000-0000-7000-8000-000000000002` (`sandbox-wallet-topup-required`): Static sandbox product that returns an action-required wallet order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPF`. - `018f0000-0000-7000-8000-000000000003` (`sandbox-merchant-attention-required`): Static sandbox product that returns a fulfillment action-required order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPG`. - `018f0000-0000-7000-8000-000000000004` (`sandbox-manual-review-required`): Static sandbox product that returns a manual-review action-required order. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPH`. - `018f0000-0000-7000-8000-000000000005` (`sandbox-failed-order`): Static sandbox product that returns a failed fulfillment response. Poll it with order_id `1CAYVN8V9qVvrLwnnSZsPJ`.
  - format `uuid`
- `quantity` (`createOrder.quantity`; integer, required)
  - min 1
- `merchant_order_ref` (`createOrder.merchant_order_ref`; string, optional, nullable) — Optional store-scoped merchant order reference. Reusing the same value for the same store returns `409 merchant_order_ref_already_used` and does not create another order. If you lose the create response, pass this value as `{id}` when polling order status.
  - maxLength 128
- `recipient` (`createOrder.recipient`; object, optional) — For voucher products, name/email/mobile are optional delivery details. For top-ups, send every canonical key advertised in recipient_fields by the catalog. PUBG normally requires player_id; Mobile Legends requires player_id and zone_id. Other products may require region_id or arbitrary configured safe keys. Send values as nonblank strings to preserve leading zeros. Missing and unconfigured fields return 422 validation_failed before order creation or fulfillment. Never substitute provider-specific keys such as userId or account_id unless that exact canonical key is configured on the Product.
  - `name` (`createOrder.recipient.name`; string, optional)
    - example `"Customer Name"`
  - `email` (`createOrder.recipient.email`; string, optional)
    - format `email`
  - `mobile` (`createOrder.recipient.mobile`; string, optional)
    - example `"+966500000000"`
  - `player_id` (`createOrder.recipient.player_id`; string, optional)
    - example `"123456789"`
  - `zone_id` (`createOrder.recipient.zone_id`; string, optional)
    - example `"1234"`
  - `server_id` (`createOrder.recipient.server_id`; string, optional)
    - example `"5678"`
  - `region_id` (`createOrder.recipient.region_id`; string, optional)
    - example `"eu"`
  - `account_tag` (`createOrder.recipient.account_tag`; string, optional)
    - example `"main"`
- `webhook_url` (`createOrder.webhook_url`; string, optional, nullable) — Optional HTTPS callback URL for this order.
  - format `uri`

## Example requests

### PUBG

```json
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "quantity": 1,
  "recipient": {
    "player_id": "00123456789"
  }
}
```

### Mobile Legends

```json
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa2",
  "quantity": 1,
  "recipient": {
    "player_id": "12345678",
    "zone_id": "1234"
  }
}
```

### Configurable Game

```json
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa3",
  "quantity": 1,
  "recipient": {
    "player_id": "00123",
    "region_id": "eu",
    "account_tag": "main"
  }
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://cardzone.ai/api/b2b/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "quantity": 1,
  "recipient": {
    "player_id": "00123456789"
  }
}
'
```

### TypeScript

```typescript
const url = 'https://cardzone.ai/api/b2b/v1/orders';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    product_id: '018f7b75-0194-726a-9814-e26efa39dfa1',
    quantity: 1,
    recipient: {player_id: '00123456789'}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://cardzone.ai/api/b2b/v1/orders"

payload = {
    "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
    "quantity": 1,
    "recipient": { "player_id": "00123456789" }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Order accepted. The returned status may be processing, fulfilled, action_required, failed, or canceled.

#### Example

```json
{
  "order_id": "1CBDzqwiovwVrtFk6nZ1Aw",
  "merchant_order_ref": "merchant-order-10001",
  "status": "processing",
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfac",
  "product_code": "psn-sa-160",
  "quantity": 1,
  "purchase_price": {
    "amount": "380.00",
    "currency": "SAR"
  },
  "recommended_retail_price": {
    "amount": "400.00",
    "currency": "SAR"
  },
  "codes": [],
  "actions": [],
  "created_at": "2026-05-18T00:29:58+03:00"
}
```

- `order_id` (`createOrder.response.201.order_id`; string, required) — Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.
  - minLength 22; maxLength 22; pattern `^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$`
- `status` (`createOrder.response.201.status`; string, required) — `processing`: accepted or still fulfilling. `fulfilled`: successful; safe to mark the partner order successful. `action_required`: inspect `actions` and take the required action. `failed`: terminal failure; inspect `failure_reason` when present. Replacement codes the store paid for can still be added to `codes`, and a dashboard retry moves the order back to `processing`. `canceled`: terminal cancellation; no fulfillment action remains.
  - one of `"processing"`, `"fulfilled"`, `"action_required"`, `"failed"`, `"canceled"`
- `product_id` (`createOrder.response.201.product_id`; string, required, nullable)
  - format `uuid`
- `quantity` (`createOrder.response.201.quantity`; integer, required)
- `actions` (`createOrder.response.201.actions`; array<object>, required) — Actions required from the API consumer. Empty when no action is needed.
  - `type` (`createOrder.response.201.actions.type`; string, required)
    - one of `"wallet"`, `"fulfillment"`
  - `code` (`createOrder.response.201.actions.code`; string, required) — Machine-readable action the API consumer should handle.
    - one of `"wallet_topup_required"`, `"merchant_attention_required"`, `"manual_review_required"`
  - `message` (`createOrder.response.201.actions.message`; string, required) — Human-readable action summary. Wallet actions include the aggregate additional top-up amount needed for all current wallet-blocked orders in the store.
    - example `"Recharge 75 SAR to resume fulfillment for all wallet-blocked orders."`
- `created_at` (`createOrder.response.201.created_at`; string, required)
  - format `date-time`
- `merchant_order_ref` (`createOrder.response.201.merchant_order_ref`; string, optional, nullable) — Merchant order reference supplied on create, when present.
- `product_code` (`createOrder.response.201.product_code`; string, optional, nullable)
- `purchase_price` (`createOrder.response.201.purchase_price`; object, optional)
  - `amount` (`createOrder.response.201.purchase_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`createOrder.response.201.purchase_price.currency`; string, required)
    - example `"SAR"`
- `recommended_retail_price` (`createOrder.response.201.recommended_retail_price`; object, optional)
  - `amount` (`createOrder.response.201.recommended_retail_price.amount`; string, required) — Decimal amount as a string
    - example `"12.00"`
  - `currency` (`createOrder.response.201.recommended_retail_price.currency`; string, required)
    - example `"SAR"`
- `code` (`createOrder.response.201.code`; string, optional, nullable) — First delivered voucher code/PIN when available
- `codes` (`createOrder.response.201.codes`; array<string>, optional) — All delivered voucher codes/PINs when available. Includes replacement codes Cardzone delivered and charged to the store, which can appear while `status` is `failed`.
- `failure_reason` (`createOrder.response.201.failure_reason`; string, optional, nullable) — Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
- `failure_code` (`createOrder.response.201.failure_code`; string, optional, nullable) — Cardzone-owned terminal failure identifier. `fulfillment_failed` is the generic failure and `player_id_incorrect` means the submitted player ID was definitively rejected. Provider messages and responses are never exposed here.
  - one of `"fulfillment_failed"`, `"player_id_incorrect"`

### 401

Missing, revoked, or unknown API key. A live key also gets this while its store is inactive, or until the store's business verification is approved and its primary user's email is verified.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`createOrder.response.401.error`; object, required)
  - `code` (`createOrder.response.401.error.code`; string, required)
  - `message` (`createOrder.response.401.error.message`; string, required)
  - `details` (`createOrder.response.401.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`createOrder.response.401.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 403

`forbidden` when the API credential lacks the required permission, or `insufficient_store_wallet_balance` when a live key's store does not meet the wallet requirement.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`createOrder.response.403.error`; object, required)
  - `code` (`createOrder.response.403.error.code`; string, required)
  - `message` (`createOrder.response.403.error.message`; string, required)
  - `details` (`createOrder.response.403.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`createOrder.response.403.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 404

The product cannot be ordered: `error.code` is `validation_failed` and `error.details` is `product_not_found` (unknown or deleted, hidden, out of stock, or no way to fulfill it for this store) or `payment_option_not_found` (no active price). `error.product_status` is `out_of_stock` or `unavailable` when the product exists.

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`createOrder.response.404.error`; object, required)
  - `code` (`createOrder.response.404.error.code`; string, required)
  - `message` (`createOrder.response.404.error.message`; string, required)
  - `details` (`createOrder.response.404.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`createOrder.response.404.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 409

merchant_order_ref has already been used for this store

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`createOrder.response.409.error`; object, required)
  - `code` (`createOrder.response.409.error.code`; string, required)
  - `message` (`createOrder.response.409.error.message`; string, required)
  - `details` (`createOrder.response.409.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`createOrder.response.409.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`

### 422

Validation failed

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "product_status": "out_of_stock"
  }
}
```

- `error` (`createOrder.response.422.error`; object, required)
  - `code` (`createOrder.response.422.error.code`; string, required)
  - `message` (`createOrder.response.422.error.message`; string, required)
  - `details` (`createOrder.response.422.error.details`; unknown, optional) — Optional field-level validation details
  - `product_status` (`createOrder.response.422.error.product_status`; string, optional) — Present on `404` product errors when the product exists but cannot be ordered: `out_of_stock` or `unavailable`, with the same meaning as the catalog `status`. Absent when the product id is unknown or deleted.
    - one of `"out_of_stock"`, `"unavailable"`


Source: https://docs.cardzone.ai/reference/orders/create/index.md