# Quickstart (/docs/quickstart)

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](/docs/authentication)) and a funded Sandbox wallet.

```bash
export OPENROAM_API_KEY="your Sandbox key"
export OPENROAM_URL="https://api.sandbox.openroam.com"
```

<Steps>
<Step>
### Check your account [#check-your-account]

[`GET /v1/account/services`](/docs/api-reference/account/get-services) confirms the key works and lists the products enabled for your account.

```bash
curl "$OPENROAM_URL/v1/account/services" -H "X-Partner-Key: $OPENROAM_API_KEY"
```
</Step>

<Step>
### Search [#search]

[`GET /v1/esims/search`](/docs/api-reference/esims/search) returns eSIM destinations that cover a country, each with its offers.

```bash
curl "$OPENROAM_URL/v1/esims/search?countryCode=FR&currency=USD&limit=5" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
```

```json
{
  "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`.
</Step>

<Step>
### Quote [#quote]

[`POST /v1/esims/quote`](/docs/api-reference/esims/quote) validates the body and returns the current price. Nothing is charged or reserved.

```bash
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": {} }]
  }'
```

```json
{
  "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.
</Step>

<Step>
### Order [#order]

[`POST /v1/esims/order`](/docs/api-reference/esims/create-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](/docs/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.

```bash
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:

```json
{
  "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`.
</Step>

<Step>
### Follow delivery [#follow-delivery]

Read the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id), or subscribe to the [`order.fulfillment.updated`](/docs/webhooks) 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.

```bash
curl "$OPENROAM_URL/v1/orders/04b817c4-05d4-4e06-954b-e2470a87b620" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
```
</Step>
</Steps>

## Next steps [#next-steps]

- Read the guide of the product you sell: [eSIMs](/docs/products/esims), [Airtime](/docs/products/airtime), [Utility](/docs/products/utility), [Gift cards](/docs/products/gift-cards), [Hotels](/docs/products/hotels) or [Flights](/docs/products/flights).
- Handle [errors](/docs/errors) and [webhooks](/docs/webhooks).
- Learn what happens to an order after purchase in [Orders](/docs/orders).
- Try other outcomes with the [Sandbox scenario header](/docs/environments#choose-a-fulfillment-outcome).