Create Bulk Order

Facilitates the creation of a new bulk order by specifying products and quantities. This API operates asynchronously; once the client submits a request, the API accepts the order immediately without initiating fulfillment. The fulfillment process occurs subsequently through asynchronous processing. Please be advised that there will be a waiting period for order fulfillment.

The Create Bulk Order API now supports multiple currencies beyond USD. If you have wallets in other currencies like GBP or EUR, you can place orders using your preferred currency. However, please note that one API order can only contain products in a single currency. For example, if you're ordering 3 products in one API request, all products must share the same currency. Otherwise, you will receive an error response.

POST /v1/orders

Request

HTTP Headers

To use this endpoint, you must include the following headers for authentication and authorization:

Header	Type	Required	Description
x-api-key	String	Yes	API key assigned to your account for service access.
Authorization	String	Yes	Bearer token to authenticate the API request.

Payload

Property	Type	Required	Default Value	Description
clientOrderNumber	String	No	None	The order number assigned by the client, used for tracking and reference purposes.
enableClientOrderNumberDupCheck	Boolean	No	false	Enable to prevent duplicate clientOrderNumber
products	ProductRequest[]	Yes		List of products included in the order.
payWithCurrency 🆕	String	No*	None	Settlement currency (ISO-4217). See rules below. Required only when the product currency is not in the customer’s balance currencies.

*payWithCurrency is required only when the product currency is not present in the customer’s balance currencies. If omitted otherwise, the system defaults to the product currency; if the customer has a single balance currency equal to the product currency, the default is applied automatically. If payWithCurrency is provided but not in the customer’s balances, the API returns UNSUPPORTED_CURRENCY.

Cross-currency settlement (payWithCurrency)

Settle an order in a currency different from the product’s currency.

Property: payWithCurrency (ISO‑4217, e.g., USD)

Rules

• If the product currency is in your balances and payWithCurrency is omitted, the order settles in the product currency (default).
• If the product currency is not in your balances, payWithCurrency is required; omitting it returns UNSUPPORTED_CURRENCY.
• If payWithCurrency is provided but not in your balances, the API returns UNSUPPORTED_CURRENCY.
• If you have a single balance currency equal to the product currency, the system defaults to that currency; you may still override it.

ProductRequest

Property	Type	Required	Default Value	Description
sku	String	Yes		The Stock Keeping Unit identifier for the product.
quantity	Integer	Yes		The quantity of the product requested in the order.

Example Request

POST /v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
x-api-key: <API_KEY>
Authorization: Bearer <BEARER_ACCESS_TOKEN>

{
  "clientOrderNumber": "1234",
  "products": [
    {
      "sku": "8PX-UF-Y5U",
      "quantity": 100
    }
  ]
}

Example Request (Cross-Currency)

POST /v2/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
x-api-key: <API_KEY>
Authorization: Bearer <BEARER_ACCESS_TOKEN>

{
  "clientOrderNumber": "1234",
  "products": [
    {
      "sku": "8PX-UF-Y5U",
      "quantity": 100
    }
  ],
  "payWithCurrency": "USD"
}

Responses

HTTP Status Codes

Status Code	Description
200	OK
400	Bad Request
409	Conflict (e.g., duplicate clientOrderNumber when duplication check is enabled)
422	Unprocessable Entity (e.g., invalid or missing payWithCurrency when required)
500	Internal Server Error

Schema

Property	Type	Nullable	Description
requestId	String	No	Unique identifier assigned to each request for tracking purposes.
data	OrderResponse	No	Order response.

OrderResponse

Property	Type	Nullable	Description
transactionId	String	No	The transaction identifier.
clientOrderNumber	String	No	The client's order number.
payWithCurrency	String	No	The currency used to settle/charge the order.
grandTotal	MoneyResponse	No	The grand total amount and currency.
createdAt	String	No	Timestamp of when the order was created.
status	OrderStatus	No	The status of the order.
products	ProductResponse[]	No	List of products in the order.
fxSummary	FxEntry[]	Yes	Summary of FX pairs/rates used when cross-currency conversion is applied. Omitted for same-currency orders.

ProductResponse

Property	Type	Nullable	Description
sku	String	No	The SKU of the product.
quantity	Integer	No	Always 1 for Instant orders.
unitPriceOriginal	MoneyResponse	Yes	Unit price in the product’s native currency before FX. Optional; omitted when same-currency.
unitPrice	MoneyResponse	No	The unit price of the product.
totalPrice	MoneyResponse	No	The total price of the product.
status	OrderStatus	No	The status of the product.

MoneyResponse

Property	Type	Nullable	Description
amount	String	No	The monetary amount.
currency	String	No	The currency of amount.

FxEntry

Property	Type	Nullable	Description
pair	String	No	Currency pair used (e.g., EUR/USD).
rate	Number	No	Applied FX rate for the pair.
asOfDate	String	No	ISO date/time when the rate was effective.

OrderStatus

Value	Type	Description
PROCESSING	String	The order is currently being processed.
COMPLETED	String	The order has been completed successfully.
CANCELLED	String	The order has been cancelled and will not be processed.

Example 200 OK Response

{
  "requestId": "c4c7b997-79a5-4bde-9f17-47ad7eac9ed4",
  "data": {
    "transactionId": "1234",
    "clientOrderNumber": "1234",
    "grandTotal": {
      "amount": "1,197.5",
      "currency": "USD"
    },
    "createdAt": "2023-10-17T09:00:00Z",
    "status": "PROCESSING",
    "products": [
      {
        "sku": "8PX-UF-Y5U",
        "quantity": 100,
        "unitPrice": {
          "amount": "9.5",
          "currency": "USD"
        },
        "totalPrice": {
          "amount": "950.00",
          "currency": "USD"
        },
        "status": "PROCESSING"
      },
      {
        "sku": "TTR-WI-YWN",
        "quantity": 10,
        "unitPrice": {
          "amount": "24.75",
          "currency": "USD"
        },
        "totalPrice": {
          "amount": "247.5",
          "currency": "USD"
        },
        "status": "COMPLETED"
      }
    ]
  }
}