Overview
Top up an existing eSIM with additional data using top-up packages. This extends the data allowance of an active eSIM without creating a new one.
Key Requirements: Top-ups require:
packageType: 'TOPUP'packageCode: TOPUP package code (e.g., “TOPUP_P3ICIKSE8”)esimId: The ID of the eSIM to top up (obtained from previous purchase or fetch)
Two-Step Process: Like purchases, the top-up API returns a transactionId. Query /api/esim/{transactionId} to get updated eSIM details with the new data balance.
Quick Start
async function topUpEsim(esimId, topupPackageCode) {
// Step 1: Purchase top-up
const response = await fetch('https://api.vellosim.com/api/esim/buy', {
method: 'POST',
headers: {
'X-API-Key': `API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageCode: topupPackageCode, // TOPUP package code (e.g., TOPUP_P3ICIKSE8)
paymentMethod: 'WALLET',
packageType: 'TOPUP',
esimId: esimId // ID of the eSIM to top up
})
});
const data = await response.json();
if (data.status !== 'SUCCESS') {
throw new Error('Top-up failed');
}
// Step 2: Fetch updated eSIM details
const esimResponse = await fetch(
`https://api.vellosim.com/api/esim/${data.transactionId}`,
{
headers: {
'X-API-Key': `API_KEY}`
}
}
);
const esimData = await esimResponse.json();
return {
transactionId: data.transactionId,
iccid: esimData.iccid,
dataRemaining: esimData.data_usage_remain,
totalVolume: esimData.totalVolume,
validityRemaining: esimData.validity_usage_remain
};
}
// Usage
const result = await topUpEsim('69125f9f56d7f09edabbaf23', 'TOPUP_P3ICIKSE8');
console.log('Top-up successful! New data:', result.dataRemaining);
Request Body
| Field | Type | Required | Description |
|---|
packageCode | string | Yes | TOPUP package identifier (e.g., “TOPUP_P3ICIKSE8”) |
paymentMethod | string | Yes | Must be “WALLET” for API users |
packageType | string | Yes | Must be “TOPUP” for top-up purchases |
esimId | string | Yes | ID of the eSIM to top up (from purchase or fetch response) |
Finding TOPUP Packages: Query /api/esim/packages?regionCode=US&type=TOPUP&packageCode=CKH533 to get available top-up packages. Top-up package codes are prefixed with TOPUP_.
Successful Response
Step 1: Purchase Response
{
"transactionId": "esim_1762812333247_7046",
"status": "SUCCESS",
"package": {
"packageCode": "TOPUP_P3ICIKSE8",
"name": "United States 10GB 30Days",
"price": 14640,
"volume": 0,
"duration": 0,
"currencyCode": "NGN"
}
}
{
"iccid": "8997250230000286674",
"transactionId": "esim_1762812333247_7046",
"totalVolume": 11261296640,
"data_usage_remain": 11261296640,
"validity_usage_remain": 37,
"expiredTime": "2026-05-09T21:56:47.000Z",
"packageDetails": {
"name": "United States 10GB 30Days",
"code": "CKH533",
"volume": 10737418240
}
}
The totalVolume and data_usage_remain are updated to reflect the added data. Values are in bytes.
Next Steps
