Skip to Content
OpenRoam Docs

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"

GET /v1/esims/search returns eSIM destinations that cover a country, each with its offers.

curl "$OPENROAM_URL/v1/esims/search?countryCode=FR&currency=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

On this page