Documentation OpenAPI
Orders / POST /v1/orders
Create an order
Create one wallet-funded order with idempotent retry protection.
Last updated on
Preferred customer API authentication. Create a personal or organization key from /my-account?tab=settings, then send Authorization: Bearer <api_key>. Query-string API keys are not supported.
In: header
Header Parameters
Required for order creation. Reuse the same key to safely retry.
8 <= length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Orderable service/product identifier returned by GET /v1/services.
1 <= lengthDestination, profile, URL, or handle required by the selected service.
1 <= length <= 512Quantity to order. Must respect the selected service minQuantity, maxQuantity, and stepQuantity.
1 <= valueOptional client metadata for reconciliation. externalOrderId is copied to the order when supplied.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/orders" \ -H "idempotency-key: stringst" \ -H "Content-Type: application/json" \ -d '{ "serviceId": "prod_123", "target": "@customer_handle", "quantity": 100, "metadata": { "externalOrderId": "client-order-1001" } }'{ "id": "ord_123", "object": "order", "status": "queued", "paymentStatus": "paid", "serviceId": "prod_123", "productId": "prod_123", "target": "@customer_handle", "quantity": 100, "amount": 250000, "currency": "NGN", "sourceSystem": "customer_api", "externalOrderId": "client-order-1001", "createdAt": "2026-05-25T10:00:00.000Z", "updatedAt": "2026-05-25T10:00:01.000Z"}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}{ "error": { "code": "string", "message": "string", "details": { "property1": null, "property2": null }, "requestId": "string" }}