# Supplier continuity

> Why a topup can occasionally be unavailable for an existing eSIM, and how FX-Port protects your agency balance when that happens.

Source: https://fx-port.com/docs/esims/supplier-continuity

An eSIM plan is provisioned on a specific mobile network operator in the destination country. FX-Port's
suppliers choose which operators serve a country, and in rare cases a supplier **changes which operator serves a
country or a package**. Operator and package availability can therefore change over time, which is why you should
read the current catalog and topup packages instead of storing them for long.

## What this means for topups

If the operator of a country changes after a traveler's eSIM was issued, the package of that eSIM can be
discontinued for this ICCID even though the eSIM itself is still active. The eSIM can keep working until it
expires, but **a topup of the old operator's package is no longer possible**: a package of the current operator
is needed, which usually means a new eSIM order rather than a topup of the old ICCID.

This is uncommon, but design for it: it is a supplier-side change, not an error of your integration.

## How FX-Port handles it

FX-Port never assumes that a topup package is still valid. The flow makes sure this situation cannot fail
silently or take your money:

1. **`GET /api/v1/esims/topup-packages/{iccid}`** asks the supplier for the exact ICCID, not for the package of the
   original order. If the supplier no longer offers a topup for this eSIM, the list is empty. The answer is kept
   for **5 minutes** per eSIM and language (`cached: true`); `force=true` asks the supplier again.
2. **`POST /api/v1/esims/topups`** debits your agency balance and records a confirmed booking **only after** the
   supplier accepts the topup. If the supplier rejects it, including because the package or operator of this ICCID
   is no longer topup-eligible, FX-Port:
   - does **not** touch your agency balance,
   - records the attempt as a `failed` booking for support, and
   - answers with a `supplier_error` (the supplier's HTTP status) so your integration can react at once.
3. Both endpoints serve only the eSIMs **your agency ordered**. An ICCID that is unknown or belongs to another
   agency is answered `404 iccid_not_found`, and the supplier is not asked.

## Recommended integration pattern

~~~bash
# 1. Check topup availability for the exact ICCID first
curl --request GET \
  --url https://api.fx-port.com/api/v1/esims/topup-packages/8900000540463077957 \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'
~~~

For an eSIM that cannot be topped up now, the list is empty:

~~~json
{
  "success": true,
  "data": { "data": [] }
}
~~~

An empty list means this eSIM cannot currently be topped up. Place a new [eSIM order](https://fx-port.com/docs/esims/orders.md)
for the traveler instead of retrying.

If packages are returned, continue with [Create eSIM topup](https://fx-port.com/docs/esims/topups.md#2-create-the-topup) using one of
the returned `package_id` values. Never reuse the `package_id` of the original order, and do not keep a topup
package for later: ask again when the traveler wants to top up.