Supplier continuity

eSIM data plans are provisioned on a specific mobile network operator in the destination country. FX-Port's eSIM suppliers source coverage from local/regional network operators per country, and in rare cases a supplier can change which operator serves a given country or package. Public eSIM partner API documentation in this space generally notes that operator and package availability can change over time, and that integrators should always fetch current package/topup data rather than caching it indefinitely.

What this means for topups

If the underlying operator for a country changes after a traveler's eSIM was issued, the original package can be discontinued for that ICCID even though the eSIM itself is still active. When that happens, the eSIM usually keeps working until it expires, but a topup on the old operator's package is no longer possible — a new package from the current operator must be used instead, which typically means issuing a new eSIM order rather than a topup on the old ICCID.

This is uncommon, but it is a real, documented behavior in the eSIM industry — not an FX-Port limitation.

How FX-Port handles it

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

1. GET /api/v1/esims/topup-packages/{iccid} always queries the fulfilling supplier live, scoped to the exact ICCID. It never returns a cached assumption based on the original order — if the supplier no longer offers a topup for that ICCID (for example, because its operator changed), the response is an empty package list.
2. POST /api/v1/esims/topups only debits your agency balance and records a confirmed booking after the supplier accepts the topup. If the supplier rejects it (including because the ICCID's package/operator is no longer topup-eligible), FX-Port:
   • does not touch your agency balance,
   • records the attempt as a failed internal booking for support visibility, and
   • returns an error response so your integration can react immediately.

Recommended integration pattern

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

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

An empty package list means this eSIM cannot currently be topped up. In that case, place a new eSIM order for the traveler instead of retrying the topup.

If packages are returned, proceed to Create eSIM Topup using one of the returned package_id values — never reuse a package_id from the original order without checking this endpoint first.