# eSIMs (/docs/products/esims)

## What you can sell [#what-you-can-sell]

OpenRoam sells data eSIM plans by destination. A destination is one country (`local`), a region such as Europe (`regional`) or the whole world (`global`). Each destination lists offers: plans with a data allowance, a validity in days and a price.

You can sell:

- **A new eSIM.** Installed at once (the default) or as a deferred entitlement that you provision later.
- **A top-up.** An extra plan added to an eSIM you already bought, addressed by its ICCID.

An eSIM has no monetary value, so there is no `inputs.value` on this product. The price guard is `inputs.maxPrice`.

## The flow [#the-flow]

<Steps>
<Step>
### Search [#search]

[`GET /v1/esims/search`](/docs/api-reference/esims/search) returns destinations with their offers, one page at a time. Filter by `countryCode`, `category`, `region`, `validityDays`, `isUnlimited` and `currency`. A country filter matches the destination's coverage, so `countryCode=FR` returns France and every regional or global destination that covers France.

Other ways to browse:

- [`GET /v1/esims/destinations`](/docs/api-reference/esims/get-destinations) lists every destination with an orderable offer, as summaries without offers.
- [`GET /v1/esims/destinations/{id}`](/docs/api-reference/esims/get-destination) returns one destination in the shape search returns.
- [`GET /v1/esims/catalog`](/docs/api-reference/esims/get-catalog) walks every destination page by page with a cursor. Continue with `nextCursor`, the same filters and the same currency until `nextCursor` is null.
- [`GET /v1/esims/compatible-devices`](/docs/api-reference/esims/get-compatible-devices) lists devices that support eSIM.

Unknown query parameters are rejected with `400 / 10001` (`UNSUPPORTED_FIELD`).
</Step>

<Step>
### Quote [#quote]

[`POST /v1/esims/quote`](/docs/api-reference/esims/quote) prices an order body. It has no side effects: nothing is charged or reserved, and a quote does not expire or bind the order. To hold a quoted price, send it as `inputs.maxPrice` in the order.
</Step>

<Step>
### Order [#order]

[`POST /v1/esims/order`](/docs/api-reference/esims/create-order) takes the same body as the quote. It needs an `Idempotency-Key` header and an API key with the `manage` permission. The response is the shared order envelope, read later with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). See [Idempotency](/docs/idempotency) and [Orders](/docs/orders).
</Step>
</Steps>

You can also buy eSIMs together with other products through [`POST /v1/orders`](/docs/api-reference/orders/create-order), where each item adds `productType: "esim"`.

## Destinations and offers [#destinations-and-offers]

A destination looks like this (shortened):

```json
{
  "id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq",
  "name": "Europe",
  "countryCode": null,
  "category": "regional",
  "logoUrl": "https://example.com/esims/europe.png",
  "description": null,
  "offers": [
    {
      "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
      "name": "Europe 3 GB 7 days",
      "description": null,
      "price": { "amount": 25.00, "currency": "USD" },
      "requiredInputs": [
        {
          "name": "isInstant",
          "type": "boolean",
          "required": false,
          "description": "Defaults to true, which creates the eSIM when the order is fulfilled. False delivers an entitlement, and the eSIM is created later through provisioning."
        }
      ],
      "details": {
        "validityDays": 7,
        "data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
        "voice": null,
        "sms": null,
        "apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
        "properties": { "withTopUp": true, "withHotspot": true, "activation": "first-use", "charge": "one-time" },
        "restrictions": { "throttle": false, "throttleSpeed": null, "expireInDays": 30 },
        "notes": [ "Data only. Calls and SMS are not included." ],
        "plan": null
      }
    }
  ],
  "details": {
    "destinationCode": "EU",
    "region": "Europe",
    "coverage": [
      { "countryCode": "FR", "name": "France", "networks": [ "4G", "5G" ], "carriers": [ "Example Mobile" ] }
    ]
  }
}
```

Things to know:

- `id` is the destination id. `publicId` on an offer is the id you quote and order with. Treat both as opaque. A destination id is never orderable; sent as a `publicId` it gives `400 / 11004`.
- `countryCode` is an ISO 3166-1 alpha-2 code for a local destination and null for a regional or global one. `details.destinationCode` is the destination's own code, such as `FR`, `EU` or `NAM`.
- `price` is indicative. The quote is authoritative.
- `details.data.amount` is in MB. It is null when `isUnlimited` is true or the amount is not known.
- `details.properties.withTopUp` tells you whether the plan can be topped up.
- After a purchase, `GET /v1/esims/destinations/{id}` with the order item's `purchasedProduct.details.destination.id` returns the coverage of the destination the eSIM was bought for.

## Required inputs [#required-inputs]

Each offer lists the `inputs` it takes in `requiredInputs`:

| `name` | `type` | Required | Listed on |
|---|---|---|---|
| `eid` | `text` | yes | Offers that require the device EID. |
| `imei2` | `text` | yes | Offers that require the device's second IMEI. |
| `travelStartDate` | `date` | yes | Offers that require the first day of travel (`YYYY-MM-DD`). A deferred purchase may send it at provisioning instead. |
| `isInstant` | `boolean` | no | Every purchase offer. `true` (the default) creates the eSIM when the order is fulfilled. `false` delivers an entitlement. |
| `iccid` | `text` | yes | Top-up offers only. See [Top-ups](#top-ups). |

A new eSIM without an input its offer lists as required fails with `400 / 10001`, reason `REQUIRED`, at `items[i].inputs.<name>`, before anything is charged. `eid` and `imei2` are needed for a deferred purchase too, because provisioning reuses the values the order recorded. `travelStartDate` is needed on an instant purchase only.

`inputs` also takes the standard `maxPrice` field (below). `requiredInputs` never lists it. `inputs` may be omitted for an offer that needs none.

## Quote and order [#quote-and-order]

Quote and order take the same body:

```json
{
  "currency": "USD",
  "referenceId": "partner-order-42",
  "items": [
    {
      "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
      "quantity": 1,
      "inputs": {
        "isInstant": true,
        "maxPrice": { "amount": 25, "currency": "USD" }
      }
    }
  ]
}
```

```bash
curl -X POST https://api.sandbox.openroam.com/v1/esims/quote \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @esim-order.json

curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @esim-order.json
```

The quote response:

```json
{
  "currency": "USD",
  "items": [
    {
      "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
      "quantity": 1,
      "name": "Europe 3 GB 7 days",
      "price": { "amount": 25.00, "currency": "USD" }
    }
  ],
  "total": { "amount": 25.00, "currency": "USD" }
}
```

Rules:

- 1 to 5 items, and at most 5 eSIMs in total. A new eSIM accepts a `quantity` above 1, and each eSIM becomes its own order item. A top-up takes `quantity` 1.
- `referenceId` is your own reference. Quote validates it and ignores it.
- `inputs.value` does not exist for eSIM. Sending it, or sending `value` or `maxPrice` beside `inputs`, fails with `400 / 10001` and reason `INVALID_VALUE`.
- `inputs.maxPrice` is `{ amount, currency }`, the highest unit price you accept, in the order currency. A current price above it fails with `409 / 11002` (`PRICE_CHANGED`) at `items[i].inputs.maxPrice`, and nothing is charged. A different currency gives `400 / 10001` (`CURRENCY_MISMATCH`). The amount must be above 0 and use no more decimals than its currency.
- Items are checked one at a time in request order. The first failing item ends the request, and quote and order report the same error for it.

## Top-ups [#top-ups]

A top-up adds a plan to an eSIM you already bought.

1. Call `GET /v1/esims/search?iccid=<iccid>`. It returns the eSIM's own destination with the offers that can top it up. Each offer lists only `iccid` in `requiredInputs`. The result is empty when no plan can top the eSIM up. With `iccid`, every filter other than `currency` is rejected (`NOT_ALLOWED`).
2. Quote and order that offer with `inputs.iccid`. Read the ICCID from the purchase's `fulfillment.result.details.iccid`.

```json
{
  "currency": "USD",
  "items": [
    { "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p", "quantity": 1, "inputs": { "iccid": "8944501234567890123" } }
  ]
}
```

<Callout type="warn">
`inputs.iccid` is what makes an item a top-up. A top-up offer has the same `publicId` as the plan sold as a new eSIM. The same item without `inputs.iccid` is quoted and ordered as a new eSIM, and no error reports the missing ICCID. Always send `inputs.iccid` with a top-up offer.
</Callout>

Top-up rules:

- `quantity` must be 1, and a top-up is always instant. `isInstant: false` gives `400 / 10001` (`NOT_ALLOWED`) at `items[i].inputs.isInstant`.
- An ICCID that is not 18 to 22 digits gives `400 / 10001` (`INVALID_VALUE`) at `items[i].inputs.iccid`.
- An unknown ICCID, or one that is not yours, gives `404 / 10004`.
- A package that can no longer top up the eSIM, for example because the eSIM was revoked, gives `400 / 10001`.
- On the order item, `purchasedProduct.details.orderType` is `topUp` (or `esim` for a new eSIM), and `fulfillment.result.details.mode` is `topUp`.

## Instant and deferred eSIMs [#instant-and-deferred-esims]

`inputs.isInstant` decides when the eSIM is created.

- **Instant** (the default): fulfillment creates the eSIM. The item becomes `fulfilled` with `mode` `instant`, `provisioning.status` `ready`, the ICCID and the installation details. While delivery is not yet confirmed, the item stays `pending`.
- **Deferred** (`isInstant: false`): fulfillment delivers an entitlement. The item is `fulfilled` with `mode` `deferred`, `provisioning.status` `notStarted`, `canProvision` true, `esimStatus` `new`, and no ICCID or `installation` yet. Create the eSIM later with [`POST /v1/esims/{id}/provisioning`](/docs/api-reference/esims/provision), where `id` is the order item id.

Provisioning a deferred eSIM:

- Send an `Idempotency-Key`. The optional body is `{ "travelStartDate": "2026-12-01" }`.
- It returns the eSIM as `GET /v1/esims/{iccid}/profile` does, and updates the item's result. `provisioning.status` moves to `processing` and then `ready`, and each published change is sent in an `order.fulfillment.updated` webhook.
- Repeating a provisioning that already succeeded, with the same key and body, returns `200` with the provisioned eSIM and provisions nothing again. While the first call is still running, the answer is `409 / 12002` with a `Retry-After` header.
- Only a deferred eSIM can be provisioned. An instant eSIM gives `400 / 10001`. An id that is not one of your eSIM purchases, such as a top-up item, gives `404 / 10004`.
- A plan that requires `travelStartDate` needs it here unless the order sent one (`400 / 10001`). A date different from the recorded one, or a new date after provisioning started, gives `409 / 10005`.
- If provisioning is refused for good, the item becomes `rejected` with `result` null and a `11001` failure, the order reads `fulfillmentFailed` (or `partiallyFulfilled` next to delivered items), and the item is refunded in full automatically.

## The order item [#the-order-item]

An eSIM order item carries `purchasedProduct`, what was bought, and `fulfillment.result`, what was delivered. There is no `value` and no `deliveredValue`.

```json
{
  "id": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
  "orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
  "productType": "esim",
  "price": { "amount": 25.00, "currency": "USD" },
  "purchasedProduct": {
    "name": "Europe 3 GB 7 days",
    "countryCode": null,
    "logoUrl": "https://example.com/esims/europe.png",
    "inputs": { "eid": null, "imei2": null, "iccid": null, "travelStartDate": null, "isInstant": true },
    "details": {
      "orderType": "esim",
      "isInstant": true,
      "destination": { "id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq", "name": "Europe", "code": "EU" }
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "details": {
        "iccid": "8944501234567890123",
        "mode": "instant",
        "provisioning": { "status": "ready" },
        "canProvision": false,
        "esimStatus": "ready",
        "profileStatus": "new",
        "installation": {
          "lpaCode": "LPA:1$smdp.example.com$example-activation-code",
          "smdpAddress": "smdp.example.com",
          "activationCode": "example-activation-code",
          "qrCodeUrl": null,
          "iosQuickInstall": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code",
          "androidQuickInstall": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code"
        },
        "pin": null,
        "puk": null,
        "phoneNumber": null,
        "data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
        "voice": null,
        "sms": null,
        "apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
        "addons": [],
        "notes": [ "Data only. Calls and SMS are not included." ],
        "fulfilledAt": "2026-10-16T05:22:43.59Z"
      }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "notAvailable", "reason": null },
    "cancellation": { "availability": "notAvailable", "reason": null },
    "update": { "availability": "notAvailable", "reason": null }
  },
  "createdAt": "2026-10-16T05:22:43.059969Z",
  "effectivePaidAmount": { "amount": 25.00, "currency": "USD" }
}
```

Before fulfillment, the same item has `fulfillment.status` `pending` and `result` null.

`purchasedProduct`:

- `inputs` echoes the item's inputs. `eid`, `imei2` and `iccid` are masked as `***` followed by the last four characters. `travelStartDate` and `isInstant` are returned as applied. An input the item did not take is null, and the price guard is not echoed.
- `details.orderType` is `esim` or `topUp`. `details.destination` is `{ id, name, code }`.

`fulfillment.result.details`:

| Key | Meaning |
|---|---|
| `iccid` | The eSIM's ICCID. It addresses the post-purchase routes and top-ups. Null until the eSIM is provisioned. |
| `mode` | `instant` or `deferred` for a new eSIM, `topUp` for a top-up. |
| `provisioning` | `{ status }`: `notStarted`, `processing`, `ready` or `failed`. |
| `canProvision` | True while a deferred eSIM waits for provisioning. |
| `esimStatus` | `new`, `procuring`, `pending`, `failed`, `ready`, `cancelled`, `revoked`, `expired` or `unknown`. |
| `profileStatus` | The installed profile's state: `empty`, `new`, `downloaded`, `installed`, `activated`, `inactive`, `deleted`, `revoked`, `expired` or `unknown`. |
| `installation` | `lpaCode`, `smdpAddress`, `activationCode`, `qrCodeUrl`, `iosQuickInstall` and `androidQuickInstall`. Null until the eSIM is provisioned. Generate a QR code from `lpaCode` when `qrCodeUrl` is null. |
| `pin`, `puk`, `phoneNumber` | Set when they are issued. |
| `data`, `voice`, `sms`, `apn` | The plan, in the shapes and units of the offer. `voice` and `sms` are null when the plan has none. |
| `addons` | Top-ups applied to the eSIM, as `{ packageName, usage }`. |
| `notes` | The plan's usage notes. |
| `fulfilledAt` | When the eSIM was delivered. |

A top-up item reads the eSIM it topped up, with `mode` `topUp`, and cannot be provisioned.

`GET /v1/orders/{id}` and the `order.fulfillment.updated` webhook ([reference](/docs/api-reference/webhooks/order-fulfillment-updated)) carry the same `result`. See [Orders](/docs/orders) for order and item statuses.

An eSIM cannot be cancelled, amended or updated once delivered. Cancel and its preview answer `422 / 18000`, amendments `422 / 18002`, and update `422 / 18004`. While the eSIM is still pending, cancel answers `409 / 18001`. A rejected eSIM is refunded in full automatically and reported by the `order-item.refunded` webhook.

## After the purchase [#after-the-purchase]

Routes under `/v1/esims/{iccid}/` read one of your eSIMs by ICCID. An ICCID that is not one of your eSIMs gives `404 / 10004`.

| Route | Returns |
|---|---|
| [`GET /v1/esims/{iccid}/profile`](/docs/api-reference/esims/get-esim) | The eSIM: plan, installation details, status, `expiresAt` and the base plan's usage. |
| [`GET /v1/esims/{iccid}/usage`](/docs/api-reference/esims/get-usage) | Current usage, with top-ups added to the plan. |
| [`GET /v1/esims/{iccid}/usage/details`](/docs/api-reference/esims/get-usage-details) | Usage plus a per-day breakdown in `usages`. |
| [`GET /v1/esims/{iccid}/usage/history`](/docs/api-reference/esims/get-usage-history) | Recorded usage readings, paged. |
| [`GET /v1/esims/{iccid}/status-events`](/docs/api-reference/esims/get-status-events) | Status changes over time, paged. |
| [`GET /v1/esims/{iccid}/location-events`](/docs/api-reference/esims/get-location-events) | Network and location events, paged. |
| [`POST /v1/esims/{iccid}/sms`](/docs/api-reference/esims/send-sms) | Sends a text message to the eSIM. Body: `{ "message": "..." }`. |

The three paged event and history routes take `page`, `limit` (1 to 100), `from` and `to` (ISO 8601 UTC).

Usage conventions:

- `start` and `end` are ISO 8601 UTC instants. Amounts use one unit each: `allowedData` and `remainingData` in MB, `allowedSms` and `remainingSms` in messages, `allowedVoice` and `remainingVoice` in whole minutes.
- An amount is null when it is unlimited (the matching `isDataUnlimited`, `isSmsUnlimited` or `isVoiceUnlimited` is then true), not reported or not included. A known allowance that is used up reads `0`.
- In `usage/details`, `date` is the calendar day the usage was counted for (`YYYY-MM-DD`), and it is not always a UTC day. `start` (inclusive) and `end` (exclusive) are the UTC instants that day runs between.
- `profile.expiresAt` is null until the eSIM is activated, then the end of the plan, extended by top-ups.

SMS:

- `200` with `{ "iccid": "..." }` means the message was sent.
- `422 / 22000` means the eSIM's plan cannot send text messages. Do not retry it.
- `502 / 10008` means the message could not be sent.

### Webhooks [#webhooks]

Subscribe to these events to follow an eSIM without polling. See [Webhooks](/docs/webhooks) for signatures, retries and deduplication by `eventId`.

- [`esim.profileStatus.updated`](/docs/api-reference/webhooks/esim-profile-status-updated) is sent when the installed profile's status changes. Its data has `orderId`, `orderItemId`, `iccid`, `start`, `end` and `profileStatus`.
- [`esim.usage.updated`](/docs/api-reference/webhooks/esim-usage-updated) is sent when usage crosses a threshold. A limited plan advances through 25, 50, 75, 90 and 100 percent used. An unlimited plan advances through 14, 7, 3 and 1 days left. Each threshold is sent at most once per eSIM, and a top-up does not reset it.
- [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) carries delivery and each provisioning change of a deferred eSIM.

```json
{
  "eventId": "677335a8-e904-ff5c-9186-c9c2690461cd",
  "eventType": "esim.usage.updated",
  "timestamp": 1792128163,
  "data": {
    "orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
    "orderItemId": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
    "iccid": "8944501234567890123",
    "start": "2026-10-16T05:30:00Z",
    "end": "2026-10-23T05:30:00Z",
    "esimStatus": "ready",
    "profileStatus": "activated",
    "packageName": "Europe 3 GB 7 days",
    "allowedData": 3072,
    "remainingData": 768,
    "isDataUnlimited": false,
    "allowedSms": null,
    "remainingSms": null,
    "isSmsUnlimited": false,
    "allowedVoice": null,
    "remainingVoice": null,
    "isVoiceUnlimited": false
  }
}
```

`timestamp` is Unix seconds. Both eSIM events address the eSIM by `orderId`, `orderItemId` and `iccid`.

## Testing in Sandbox [#testing-in-sandbox]

Use [Sandbox](/docs/environments) with your Sandbox key. Authentication, pricing, wallet payment, refunds and webhooks behave as in production. The catalog is synthetic: prices and outcomes are test data, and the install details cannot install a working eSIM.

### Scenarios [#scenarios]

`POST /v1/esims/order` and the shared `POST /v1/orders` accept the `OpenRoam-Sandbox-Scenario` header:

| Value | Result |
|---|---|
| Omitted or `success` | The ordinary successful result. |
| `fulfillment.rejected` | The order is accepted and paid, then fulfillment is rejected. The item is refunded automatically. |
| `fulfillment.pending` | The item stays `pending` without blocking, and becomes eligible for success after about 15 minutes. |
| `fulfillment.late_success` | Pending, then success after about 2 minutes. |
| `fulfillment.late_rejected` | Pending, then rejection after about 2 minutes. |

```bash
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "OpenRoam-Sandbox-Scenario: fulfillment.late_success" \
  -H "Content-Type: application/json" \
  -d @esim-order.json
```

- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. The same key with a different scenario returns `409`.
- Search, quote and reads take no scenario header. Sending it there, or outside Sandbox, returns `400 / 10001` (`NOT_ALLOWED`). An unknown, empty or repeated value returns `400 / 10001` (`INVALID_VALUE`).
- Timing is approximate and is not a guarantee. A pending item may show `fulfillment.progress` with code `CONFIRMING_OUTCOME`. For an instant eSIM or a top-up, `result` is null until the outcome arrives. A deferred eSIM still delivers its entitlement at checkout, and the timing applies to its later provisioning.
- By default Sandbox fulfillment takes a few seconds, so read the order again before you assume a final state.

### Sandbox catalog [#sandbox-catalog]

The Sandbox catalog has 73 destinations and 587 finite data-only plans: 64 countries, eight regions and a global destination. There are no unlimited, voice or SMS plans. Do not hardcode offer ids: search returns them. These plans cover the input and top-up cases:

| Destination | Data | Validity | Extra inputs | Top-up |
|---|---:|---:|---|---|
| Azerbaijan (`AZ`, local) | 1024 MB | 7 days | none | yes |
| Azerbaijan (`AZ`, local) | 1024 MB | 3 days | `eid` | no |
| Azerbaijan (`AZ`, local) | 2048 MB | 7 days | `imei2` | no |
| Azerbaijan (`AZ`, local) | 3072 MB | 10 days | `travelStartDate` | no |
| Azerbaijan (`AZ`, local) | 5120 MB | 30 days | `eid`, `imei2`, `travelStartDate` | yes |
| Europe (`EU`, regional) | 3072 MB | 7 days | none | yes |

Find them with `GET /v1/esims/search?countryCode=AZ&category=local`, optionally with `validityDays`. For regional coverage use `countryCode=FR&category=regional` and pick the destination whose `details.destinationCode` is `EU`. For global coverage use `countryCode=US&category=global`.

Use synthetic inputs such as `eid` `89049032000000000000000000000001` and `imei2` `490154203237518`. Set `travelStartDate` to tomorrow's UTC date. To test a deferred eSIM with the 3072 MB / 10 day plan, order with `inputs.isInstant: false` and send the date at provisioning.

Sandbox behavior to expect:

- An instant purchase gives each eSIM its own ICCID. `qrCodeUrl` can be null, so generate a QR code from `lpaCode`.
- A top-up adds its validity to the existing eSIM. Top-up search on an eSIM from a plan marked "no" is empty.
- A Sandbox eSIM is never activated and nothing consumes data. Usage shows the plan's allowance plus completed top-ups, `usage.end` and `profile.expiresAt` stay null, and `usage/details` returns no daily events.
- `POST /v1/esims/{iccid}/sms` answers `200` with `{ iccid }` and sends no real message.

## Errors [#errors]

Paths below are for the `items[]` bodies. They are prefixed with `items[i].` on quote, order and the shared order.

| Status / code | When | Path (`reason`) |
|---|---|---|
| `400 / 10001` | A new eSIM is missing an input its offer requires | `inputs.<name>` (`REQUIRED`) |
| `400 / 10001` | `inputs.value`, or `value` or `maxPrice` beside `inputs` | the field path (`INVALID_VALUE`) |
| `400 / 10001` | `inputs.maxPrice` in another currency than the order | `inputs.maxPrice.currency` (`CURRENCY_MISMATCH`) |
| `400 / 10001` | Top-up with `isInstant: false`, or a `quantity` other than 1 | `inputs.isInstant` (`NOT_ALLOWED`), `quantity` (`INVALID_VALUE`) |
| `400 / 10001` | Invalid ICCID | `inputs.iccid` (`INVALID_VALUE`) |
| `400 / 10001` | Unknown query parameter, invalid filter, or a malformed or mismatched catalog cursor | the parameter |
| `400 / 11004` | Unknown, malformed or foreign `publicId`, an item id, or an offer of another product | `items[i]` (`EXPIRED_OR_INVALID`) |
| `409 / 11003` | The offer cannot be sold now | `items[i]` (`UNAVAILABLE`) |
| `409 / 11002` | The current price is above `inputs.maxPrice` | `inputs.maxPrice` (`PRICE_CHANGED`) |
| `404 / 10004` | Unknown or foreign ICCID, unknown destination | none |
| `403 / 10003` | eSIM is not enabled for your account, or the key lacks the `manage` permission | `service` (`SERVICE_NOT_ENABLED`) |
| `422 / 22000` | SMS to an eSIM whose plan cannot send texts | none |
| `502 / 10008` | SMS could not be sent | none |

Check which services are enabled with [`GET /v1/account/services`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format and the remaining codes, see [Errors](/docs/errors).

## Next steps [#next-steps]

- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status, cancellation and amendments.
- [Webhooks](/docs/webhooks) for signing and retries.