Quickstart
Search, quote and order an eSIM in Sandbox, then follow its delivery.
This walkthrough buys an eSIM in Sandbox with curl. Every product follows the same steps; only the search parameters and the inputs differ.
You need a Sandbox API key with the manage permission (see Authentication) and a funded Sandbox wallet.
export OPENROAM_API_KEY="your Sandbox key"
export OPENROAM_URL="https://api.sandbox.openroam.com"Check your account
GET /v1/account/services confirms the key works and lists the products enabled for your account.
curl "$OPENROAM_URL/v1/account/services" -H "X-Partner-Key: $OPENROAM_API_KEY"Search
GET /v1/esims/search returns eSIM destinations that cover a country, each with its offers.
curl "$OPENROAM_URL/v1/esims/search?countryCode=FR¤cy=USD&limit=5" \
-H "X-Partner-Key: $OPENROAM_API_KEY"{
"items": [
{
"id": "destn_...",
"name": "France",
"countryCode": "FR",
"category": "local",
"logoUrl": "https://...",
"description": null,
"offers": [
{
"publicId": "esim_...",
"name": "France 5 GB 30 days",
"description": null,
"price": { "amount": 9.5, "currency": "USD" },
"requiredInputs": [
{ "name": "isInstant", "type": "boolean", "required": false, "description": "..." }
],
"details": { "...": "plan details" }
}
]
}
],
"pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 5, "hasMore": false, "page": 1, "totalPages": 1 }
}Pick an offer and keep its publicId. Its requiredInputs lists the inputs the order needs; add every required one under inputs.
Quote
POST /v1/esims/quote validates the body and returns the current price. Nothing is charged or reserved.
curl -X POST "$OPENROAM_URL/v1/esims/quote" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"items": [{ "publicId": "esim_...", "quantity": 1, "inputs": {} }]
}'{
"currency": "USD",
"items": [
{ "publicId": "esim_...", "quantity": 1, "name": "France 5 GB 30 days", "price": { "amount": 9.5, "currency": "USD" }, "details": {} }
],
"total": { "amount": 9.5, "currency": "USD" }
}Order with the publicId the quote returns: for hotels, flights and gift cards it can differ from the one you sent.
Order
POST /v1/esims/order takes the same body, plus an Idempotency-Key header: a new UUID for each purchase. Keep the key until you have the response, so a retry after a timeout cannot buy twice (see Idempotency).
To cap the price, send the quoted unit price as inputs.maxPrice. A higher price is refused with 409 / 11002 and nothing is charged.
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "$OPENROAM_URL/v1/esims/order" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"referenceId": "my-order-42",
"items": [{
"publicId": "esim_...",
"quantity": 1,
"inputs": { "maxPrice": { "amount": 9.5, "currency": "USD" } }
}]
}'The response is the order. OpenRoam charged your wallet and is delivering the item:
{
"id": "04b817c4-05d4-4e06-954b-e2470a87b620",
"origin": { "channel": "api" },
"status": "processing",
"total": { "amount": 9.5, "currency": "USD" },
"refunded": { "amount": 0, "currency": "USD" },
"payment": { "status": "completed", "method": "balance", "amount": { "amount": 9.5, "currency": "USD" }, "wallet": null, "failure": null },
"items": [
{
"id": "5d6650ea-03f0-4a24-94f8-0c5d66a567e7",
"orderId": "04b817c4-05d4-4e06-954b-e2470a87b620",
"productType": "esim",
"price": { "amount": 9.5, "currency": "USD" },
"purchasedProduct": { "name": "France 5 GB 30 days", "...": "..." },
"fulfillment": { "status": "pending", "result": null, "failure": null }
}
],
"timeline": [{ "status": "processing", "occurredAt": "2026-11-16T10:00:00Z" }],
"createdAt": "2026-11-16T10:00:00Z",
"updatedAt": "2026-11-16T10:00:00Z",
"fulfillmentVersion": 1
}If your wallet cannot pay, the order is refused with 402 / 16000 and nothing is kept. Top up, then send the same request with the same Idempotency-Key.
Follow delivery
Read the order with GET /v1/orders/{id}, or subscribe to the order.fulfillment.updated webhook. When the item's fulfillment.status is fulfilled, fulfillment.result holds what was delivered: for an eSIM, the details your customer needs to install it.
curl "$OPENROAM_URL/v1/orders/04b817c4-05d4-4e06-954b-e2470a87b620" \
-H "X-Partner-Key: $OPENROAM_API_KEY"Next steps
- Read the guide of the product you sell: eSIMs, Airtime, Utility, Gift cards, Hotels or Flights.
- Handle errors and webhooks.
- Learn what happens to an order after purchase in Orders.
- Try other outcomes with the Sandbox scenario header.