> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# eSIM overview

> A catalog priced in USD, a quote in your currency, and a profile someone installs on a phone.

An eSIM sells mobile data abroad. Your customer keeps their own number and their own SIM; the eSIM is a second profile their phone downloads and uses for data while they travel.

Three objects, and one of them is a physical fact about a handset.

```mermaid theme={null}
flowchart LR
    C["Catalog<br/>destinations → plans<br/>priced in USD"] --> Q["Quote<br/>what your account pays<br/>~2 minutes"]
    Q --> O["Order<br/>debits, then provisions"]
    O --> P["eSIM<br/>install → in use → depleted"]
```

## The catalog is USD; you may pay in anything

This is the part that differs from every other service here. Plans are priced in **USD**, because that is what the network wholesales in. The account you pay from can hold any currency you hold.

| Your account | What happens |
| - | - |
| USD | Nothing to convert. Buy directly; a quote is optional. |
| Anything else | [Quote](/api-reference/esim/quote-a-purchase) first. You get an `fxQuoteId` and a held rate; send the id when you buy. |

A quote is bound to one account, one plan, and one price, and backs exactly one order. It lapses in about two minutes — long enough for a customer to read a confirmation screen, short enough that the rate is still real.

## Catalog

Two levels, both read-only and paged.

| Level | What it is | Example |
| - | - | - |
| Destination | Where the data works | `US`, `!EU`, `!GL` |
| Plan | An allowance for a period | 5 GB for 30 days |

```json theme={null}
{
  "slug": "united-states-5gb-30d-pkgus5gb",
  "region": { "code": "US", "name": "United States", "kind": "country" },
  "data": { "totalBytes": "5368709120", "display": "5 GB" },
  "validityDays": 30,
  "price": { "amount": "999", "currency": "USD", "display": "9.99" },
  "supportsTopUp": true
}
```

A destination `code` is a two-letter country code, or a provider bundle code such as `!EU`. Treat both as opaque strings and read them from the catalog — it is synchronised from the network and can change.

<Note>
  The eSIM catalog uses the same page shape as bill payments: `totalPages` rather than `pageCount`, and no `hasNext` or `hasPrevious`.
</Note>

## Order

An order debits immediately and provisions afterwards. It comes back `provisioning` far more often than `completed`, and that is the normal path rather than a problem.

| Status | Meaning |
| - | - |
| `provisioning` | Paid for, being set up with the network. Seconds, usually. |
| `completed` | The eSIM exists. `profileIds` names it. |
| `failed` | The network could not issue it. |
| `refunded` | Failed, and the money is already back. |
| `partially_refunded` | Fewer issued than paid for; the difference is back. |

You never claim a refund. A failed order returns the money itself, in the currency it took, whatever the exchange rate has done since.

## eSIM

The profile a phone installs. Its whole life is data and time running out.

| Status | Meaning |
| - | - |
| `pending` | Ordered, not yet allocated. |
| `ready` | Installable. Nothing has used it. |
| `in_use` | Installed and carrying data. |
| `depleted` | Allowance spent. [Top it up](/api-reference/esim/add-data-to-an-esim) rather than reissuing. |
| `expired` | Validity elapsed. |
| `suspended` | Paused by you. Reversible. |
| `cancelled` | Cancelled before use, and refunded. |
| `revoked` | Torn down permanently. Not refunded. |

Only `ready` can be cancelled for a refund, and only while nothing has been used. Once data has flowed the network has been paid, and revoking is all that is left.

## Installation is a device problem

[Install details](/api-reference/esim/get-install-details) come in three forms, and you should offer them in this order:

1. **`universalLinkUrl`** — one tap, nothing to scan or type.
2. **`qrCodePayload`** — render as a QR. It must be scanned *from another device*; a phone cannot scan its own screen.
3. **`manual`** — the SM-DP+ address and activation code, typed by hand.

<Warning>
  The activation code installs a working SIM. It is a credential: show it to the person the eSIM is for, and keep it out of your logs.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.