# Managing eSIMs

## Finding an eSIM

`POST /myesim` lists your eSIMs, newest first. Filter by `transaction_id`, `iccid` (an exact
match when you pass a full 18–22 digit ICCID), `no_order`, `package_name` or `esim_status`.
Page with `page` and `per_page` (max 100).

## Giving it to your customer

| Field | Use |
| --- | --- |
| `qrCodeUrl` | Image of the QR code to scan |
| `publicUrl` / `shortUrl` | Install page you can send in a chat |
| `ac` | LPA activation code for manual entry |
| `apn` | APN, if the device asks for one |

You can also fetch links on demand with `GET /public-esim-link?esimTranNo=...`.

## Usage

- [Webhooks](/webhooks) (`DATA_USAGE`, `ESIM_STATUS`) push changes to you. This is the recommended way.
- `orderUsage` and `esimStatus` in `/myesim` are synced periodically.
- `GET /esim-live-usage?esimTranNo=...` asks the network provider directly. It's slower, but
  current.

## Lifecycle actions

| Action | Endpoint | Refund | Undo |
| --- | --- | --- | --- |
| Pause data | `POST /suspend` | — | `POST /unsuspend` |
| Cancel an eSIM that was **never installed** | `POST /cancel-esim` | Yes, to balance | No |
| Permanently disable | `POST /revoke` | No | No |

All of them take the eSIM's `iccid` and the `transaction_id` of the purchase it came from.
`cancel-esim` also needs `package_code`.