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

# 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:

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

An empty list means this eSIM cannot currently be topped up. Place a new eSIM order for the traveler instead of retrying.

If packages are returned, continue with Create eSIM 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.