Skip to main content
GET
/
esim
/
{iccid}
/
topups
Get Top-up Packages
curl --request GET \
  --url https://api.fyatu.com/api/v3/esim/{iccid}/topups \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "esimId": "<string>",
    "destination": "<string>",
    "packages": [
      {
        "packageId": "<string>",
        "name": "<string>",
        "data": {
          "amount": 123,
          "display": "<string>",
          "isUnlimited": true
        },
        "validity": {
          "days": 123
        },
        "price": {
          "amount": 123,
          "currency": "<string>"
        }
      }
    ],
    "total": 123
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Retrieve available top-up packages for an existing eSIM. Top-ups add data or extend validity without requiring a new eSIM installation.

​
Path Parameters

ParameterTypeDescription
iccidstringThe eSIM’s ICCID (also accepts esimId for backwards compatibility)

​
How Top-ups Work

  1. Same eSIM: User keeps their current eSIM profile
  2. Data Added: Additional data is credited to the eSIM
  3. Validity Extended: Some top-ups extend the validity period
  4. No Reinstallation: No QR code scanning required

​
Response Fields

FieldTypeDescription
iccidstringThe eSIM’s ICCID
esimIdstringThe eSIM identifier
destinationstringeSIM’s destination (determines available packages)
packagesarrayAvailable top-up packages
totalintegerNumber of available packages

​
Package Object

FieldTypeDescription
packageIdstringPackage ID (use for top-up)
namestringPackage name
data.amountintegerData in MB
data.displaystringHuman-readable data
data.isUnlimitedbooleanWhether unlimited
validity.daysintegerAdded validity days
price.amountnumberPrice in USD

​
Example Usage

const iccid = '8910300000000012345';

// Get available top-ups
const response = await fetch(`https://api.fyatu.com/api/v3/esim/${iccid}/topups`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const { data } = await response.json();

console.log(`Top-up packages for eSIM in ${data.destination}:`);

data.packages.forEach(pkg => {
  console.log(`${pkg.name}: ${pkg.data.display} / ${pkg.validity.days} days - $${pkg.price.amount}`);
});

// Show to user for selection
// Then call POST /esim/{iccid}/topup with selected packageId

​
Example Response

{
  "success": true,
  "status": 200,
  "message": "Top-up packages retrieved successfully",
  "data": {
    "iccid": "8910300000000012345",
    "esimId": "ESIM-20260105-ABC12345",
    "destination": "Turkey",
    "packages": [
      {
        "packageId": "merhaba-topup-1gb",
        "name": "Top-up 1GB",
        "data": {
          "amount": 1024,
          "display": "1 GB",
          "isUnlimited": false
        },
        "validity": {
          "days": 7
        },
        "price": {
          "amount": 3.50,
          "currency": "USD"
        }
      },
      {
        "packageId": "merhaba-topup-3gb",
        "name": "Top-up 3GB",
        "data": {
          "amount": 3072,
          "display": "3 GB",
          "isUnlimited": false
        },
        "validity": {
          "days": 30
        },
        "price": {
          "amount": 8.00,
          "currency": "USD"
        }
      }
    ],
    "total": 2
  }
}

​
When Top-ups Are Available

Top-ups are only available when:
  • The eSIM is in active or inactive status
  • Top-up packages exist for the eSIM’s destination
  • The eSIM’s provider supports top-ups
Not all destinations have top-up packages available. If the packages array is empty, the eSIM cannot be topped up and a new eSIM must be purchased.

​
Error Handling

Error CodeHTTPDescription
ESIM_NOT_FOUND404eSIM doesn’t exist or not owned by you
REGION_NOT_FOUND400Can’t determine eSIM’s region

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

​
iccid
string
required

eSIM ICCID (19-20 digits) or esimId (ESIM-XXXXXXXX)

Response

Top-up packages retrieved successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object
​
meta
object