Orders API creates a service order from an approved catalogue package.
Use it after the customer selects a package and confirms checkout in your experience. Store both your partner order ID and the Onyx order ID so support, billing, activation, and reconciliation can follow the same record.
Create Order
POST /v1/partner/orders
Required header:
idempotency-key
Request body:
{
"packageId": "onyx-connect-japan-10gb-30d",
"partnerOrderId": "partner-order-10001",
"customerReference": "customer-42"
}
packageId must reference a package in the current approved catalogue.
partnerOrderId should be unique in your system.
customerReference is optional. Use it only when it helps your support or reconciliation flow.
Create Order Response
A new order returns 201.
An idempotent replay of the same order returns 200.
{
"data": {
"order": {
"orderId": "pp_order_10001",
"partnerOrderId": "partner-order-10001",
"customerReference": "customer-42",
"packageId": "onyx-connect-japan-10gb-30d",
"catalogueVersion": "onyx-connect-sdk-v1",
"status": "esim_ready",
"currency": "USD",
"onyxPartnerNetPriceUsd": 11.6,
"createdAt": "2026-06-11T00:00:00.000Z",
"updatedAt": "2026-06-11T00:00:01.000Z"
}
}
}
Get Order
GET /v1/partner/orders/{orderId}
Use this endpoint to refresh order state after checkout, support contact, activation, refund review, or a retry.
Order States
Current order states are:
createdreservedprovisioningesim_readyinstalledfailedmanual_reviewrefunded
Show the state returned by Onyx. Do not invent a different order lifecycle.
Safe Retries
Retry order creation with the same idempotency key only when you are retrying the same request body for the same customer action.
If you reuse an idempotency key with a different request body, the API returns idempotency_conflict.
Errors
unknown_package means the package cannot be used for the order.
order_not_found means the order ID is not available to your partner account.
idempotency_conflict means the idempotency key was already used for a different order request.