Inspect usage and add a top-up
Use this guide to add data to an existing eSIM. You need permission to read the eSIM and purchase a package, plus sufficient wallet funds. Top-up availability depends on the profile, existing packages, and selected offer.
1. Inspect the active packages
Open the profile from eSIMs and review Data packages. With the API, list the eSIM's packages and inspect their status, expiry, and balance.
total_bytes is the purchased allowance. Null used_bytes, remaining_bytes, or used_percent means no measurement is available. Use balance.as_of for the last balance update time; before usage is reported, this can be the package delivery time. observed_at is a network measurement time when supplied. Neither a missing report nor an old report establishes zero remaining data. Daily usage history is not currently available.
2. List compatible offers
Select Top up on the eSIM, or call List compatible offers for that profile. Use a returned offer rather than choosing from the general catalog. Coverage in the same country does not establish compatibility.
If a top-up is unavailable, read available_actions on the eSIM for the reason. An unfinished order or the package limit can prevent another purchase. Resolve the existing order before trying again.
3. Review effective terms
Show the selected offer's allowance, coverage, published price and currency, and validity. Compare package validity with the eSIM's remaining service period. A purchase that would shorten validity requires explicit acceptance through acknowledge_shortened_validity.
A top-up creates another package. It does not change an existing package's balance or extend that package's expiry. Check the new package's activation and expiry after delivery.
4. Approve and follow the order
Confirm the purchase in the dashboard. With the API, create an order using the existing esim_id, selected offer_id, quoted offer_revision, and expected_price. Save the order ID and an Idempotency-Key for retries.
Follow the order in Orders, or get the order through the API. Inspect status after both 201 and 202 responses. If the response is lost, retry the same request with the same key; do not create a replacement purchase while the outcome is uncertain.
5. Check the resulting package
When the order is completed, use its package_id to get the new package. Confirm the target eSIM, coverage, and allowance match the purchase. A package awaiting first use can have no activation or expiry timestamp yet.
Troubleshooting
If the order is complete but a balance remains unknown, compare package status and report timestamps. Reporting can lag device usage; ordering again does not resolve that delay. If a purchase fails, inspect its failure details and any credit reference before retrying.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic.