Customer-visible improvements and API contract changes, with practical migration guidance.
Examples use synthetic identifiers. Dates describe when a change became available. App improvements are listed separately from API availability.
16 November 2026 · API · Breaking change
Compatible top-up catalogs
Plan lists for an existing eSIM now verify compatibility with that eSIM. A destination must be supplied so only relevant plans need to be checked.
Why this changed
Previously, a listed plan could require a different eSIM. Customers could select it as a top-up and encounter a failure at checkout. Compatibility is now checked before a plan is offered.
Request change
Previous
GET /v1/esim/example_esim/packages
Now
GET /v1/esim/example_esim/packages?country=VA
Response change
The response envelope is unchanged. The list contains only compatible plans; it can be empty even if plans for a new eSIM are available. Fields below are abbreviated to show the change.
Previous list
{
"status": { "code": 200, "msg": "" },
"response": [
{ "id": "example_compatible_plan" },
{ "id": "example_other_plan" }
]
}New list
{
"status": { "code": 200, "msg": "" },
"response": [
{ "id": "example_compatible_plan" }
]
}
Migration steps
- Include the destination's two-letter country code in
country. - Fetch plans again when the selected eSIM or destination changes. Do not reuse a general catalog as a top-up list.
- If the compatible list is empty, offer plans for a new eSIM as a distinct purchase.
- A missing destination returns HTTP
422. A temporary verification failure returns an error, rather than an unverified plan list; offer a retry.
16 November 2026 · Orders · Fix
Clearer failures and refund handling
Incompatible top-ups are rejected before the wallet is charged. Confirmed failed purchases show a failed order and return the wallet charge. App wallet refunds are applied once per failed order. A response timeout alone does not establish whether a purchase succeeded.
If an outcome is pending verification, check the order status before submitting another purchase. In the app, another attempt for the same unresolved plan and eSIM cannot debit the wallet again.
Previous failure behavior
Some unsuccessful top-ups returned a generic server error after charging the wallet, and the order could remain in progress. Relevant response fields are abbreviated below.
{
"status": { "code": 500 },
"response": { "status": "inprogress" }
}New: separate eSIM required
The incompatible selection now returns HTTP 409 before charging the wallet or creating a purchase order. Relevant response fields:
{
"status": {
"code": 409,
"msg": "This plan requires a separate eSIM. Choose a new eSIM to use this plan."
},
"response": {
"compatible": false,
"requires_new_esim": true,
"message": "This plan requires a separate eSIM. Choose a new eSIM to use this plan."
}
}HTTP 409 indicates a selection conflict. Offer a separate eSIM explicitly; do not silently change the customer's selection.
iOS app · Upcoming
Top-ups and new eSIMs are separate choices
Top-up selection will show only verified plans for the selected eSIM. A separate Get a separate eSIM option will explain that a new installation is required. Checkout will identify the existing eSIM or clearly say New eSIM. Plan sizes and durations will display consistently in the list and checkout, and customers can return to plan selection before paying.
This entry describes the next app update. It does not indicate App Store availability.