Resolve an eSIM service issue
Start with the customer's order or eSIM ID and access to the workspace that owns it. Check purchase, installation, and network service separately: a completed purchase does not confirm that the phone has connected.
1. Identify the service
Find the purchase in Orders or the profile in eSIMs. Confirm the affected customer and profile before taking action. With the API, get the order and get the eSIM.
Retain the order, eSIM, package, and subscription references relevant to the case. Keep installation credentials out of routine case notes.
2. Check the reported state
An order in charging may need wallet funds. provisioning or pending means the purchase is unfinished. failed carries failure details and any credit reference. For a completed order, continue with its eSIM and package rather than placing another order.
If the order page shows Waiting for funds, use Top up wallet to add funds, then Retry now to retry the existing purchase. Use Cancel order if you no longer want the unfunded purchase, and check its final status. See purchase recovery for funding and cancellation outcomes.
On the eSIM page, review Device installation, Data packages, and Purchase history. Check installation state and package balances with their timestamps. An absent installation report means the result is unknown. A null consumption value means there is no measurement; it does not establish unused or depleted data.
3. Choose the recovery step
| Symptom | Next step |
|---|---|
| Purchase is waiting for funds | Check the required wallet balance and follow purchase recovery. |
| Installation link did not arrive | Inspect delivery history and its failure code before resending. |
| Profile will not install | Record the device error and follow the installation guide. |
| Installed profile has no data | Check package state, covered countries, selected data line, and roaming settings. |
| Renewal stopped | Inspect the subscription's stop reason and period history. |
4. Apply an available action
Check available_actions on the eSIM before offering a top-up, suspension, resume, or release. A disabled action includes a reason. Permissions, profile state, or network support may prevent the action, and availability can change before you submit it.
Choose the action that matches the intended result:
| Intended result | Action and effect |
|---|---|
| Add data to an existing profile | Buy a compatible top-up. An expired eSIM can return to active service after a completed compatible top-up. |
| Pause mobile data temporarily | Suspend the eSIM. Package validity and the eSIM service period keep running. |
| Restore a suspended profile | Resume the eSIM, then verify its status and remaining package validity. |
| Stop scheduled purchases | Cancel automatic renewal. Delivered data keeps its own expiry. |
| Permanently retire the profile | Release the eSIM. It cannot be used again, remaining data is forfeited, and release does not issue a refund. |
Before release, resolve any order still in progress. Review the remaining balance and accept its loss when prompted. API callers must send acknowledge_balance_forfeit=true when unexpired balance remains. Removing the profile from a phone is a device action; use the subscription controls to stop renewal.
5. Confirm the outcome
Read the affected resource again after an accepted request. A pending operation can later fail or return to its previous state. Confirm the final order, package, or eSIM status before telling the customer the action completed.
If installation is reported complete, ask the customer to test mobile data in a covered destination. Device connectivity is a separate check from the reported installation status.
Troubleshooting
Keep an unresolved purchase under its existing order ID. Retrying with a new purchase can create another charge without resolving the first. If the outcome remains uncertain, contact support with the order status, relevant timestamps, and the last error.
Prepare a support handoff
Record the customer's symptom, device model, destination, relevant resource IDs, and steps already attempted. Include failure codes and report times so support can distinguish stale information from a failed operation.
For an installation issue, include the method used and exact device error. Do not include QR codes, activation codes, or secret installation links in an unrestricted support conversation.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic.