List orders
GET /api/v1/external/orders
Returns the tenant's orders, paginated, with optional filters. Requires scope orders:read.
Query parameters
| Parameter | Type | Description |
|---|---|---|
status | enum | PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED, CANCELLED. |
userId | UUID | Filter by customer id. |
productId | UUID | Filter by product. |
variationId | UUID | Filter by variation. |
dateFrom | ISO 8601 | Minimum date (inclusive). |
dateTo | ISO 8601 | Maximum date (exclusive). |
page | int | Page (default 1). |
limit | int | Page size (default 20, max 100). |
Request
curl "https://api.nuvlyx.com/api/v1/external/orders?status=COMPLETED&limit=10" \
-H "Authorization: Bearer nvl_live_YOUR_TOKEN"Get an order
GET /api/v1/external/orders/:id
Returns a single order with all its items, post-sale instructions and, if delivered,
decrypted license credentials. Requires scope orders:read.
Security: credentials are only sent over HTTPS and never appear in logs. Treat the response as sensitive data.
Create an order
POST /api/v1/external/orders
Creates an order on behalf of a customer. The customer is identified by
customerId or customerPhone (E.164, must be linked via the
storefront's profile). Requires scope orders:write.
Payment: the customer's wallet. If the balance is not enough for the total,
the API responds 400 with a clear message — top up the wallet first via
POST /external/customers/:id/wallet/recharge and retry.
Body
| Field | Type | Description |
|---|---|---|
customerId | UUID | Customer UUID. Mutually exclusive with customerPhone. |
customerPhone | E.164 | Customer's linked phone. Mutually exclusive with customerId. |
items | array | List of { variationId }. Repeat the same variationId N times for quantity N. Max 20. |
notes | string | Internal notes (optional). |
Request
curl -X POST https://api.nuvlyx.com/api/v1/external/orders \
-H "Authorization: Bearer nvl_live_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customerPhone": "+573001234567",
"items": [
{ "variationId": "abc12345-…" },
{ "variationId": "abc12345-…" }
]
}'
Errors
400 — Insufficient balance, out of stock, or missing customerId/customerPhone.403 — Token missing the orders:write scope.404 — Customer not found or phone not linked.