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.
balance.total_bytes is the purchased allowance. Null used_bytes, remaining_bytes, or used_percent means no measurement is available. Keep those values unknown in your application.
Read the eSIM's balance_reporting field to decide what to display. If it is unavailable, show the purchased allowance without presenting it as measured remaining data. If it is available, consumption can still be unknown until a report arrives. Daily usage history is separate and is currently unavailable.
Use balance.as_of for the last balance update time; before consumption is reported, this can be the package delivery time. balance.observed_at is the network measurement time when supplied. Show the timestamp with measured usage so the customer can recognize a delayed report.
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. Refresh compatible offers before submitting: an offer can become unavailable between selection and purchase.
An eSIM in expired is dormant and can return to active after a compatible top-up completes. Check the available action and compatible offers before deciding that the installed profile needs replacement.
3. Review effective terms
Show the selected offer's allowance, coverage, published price and currency, and validity. Compare the new package's validity with the eSIM's active_until service boundary when present. If that boundary would cut the purchased validity short, the order returns 409 with the effective validity. Show the shorter period and obtain acceptance before setting acknowledge_shortened_validity: true.
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, the offer's revision as offer_revision, and its pricing.price as expected_price. Omit subscriber_id; a top-up retains the existing assignment. Save the order ID and an Idempotency-Key for retries.
If the accepted price or revision changed, fetch the current offer and confirm the new terms before submitting another purchase. Copy the returned price amount and currency without conversion or rounding.
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. The top-up uses the installed profile; you do not need to install a new eSIM. 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.