Skip to main content
POST
/
esim
/
{iccid}
/
refresh
Refresh eSIM Data
curl --request POST \
  --url https://api.fyatu.com/api/v3/esim/{iccid}/refresh \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "status": 200,
  "message": "<string>",
  "data": {
    "esimId": "<string>",
    "iccid": "<string>",
    "status": "ready",
    "package": {
      "id": "<string>",
      "name": "<string>",
      "destination": "<string>",
      "dataGb": 123,
      "validityDays": 123
    },
    "usage": {
      "dataUsedMb": 123,
      "dataTotalMb": 123,
      "dataRemainingMb": 123,
      "percentageUsed": 123
    },
    "validity": {
      "activatedAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "daysRemaining": 123
    },
    "activation": {
      "qrCodeUrl": "<string>",
      "manualCode": "<string>",
      "appleInstallUrl": "<string>"
    },
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Refresh eSIM usage data from the provider to get real-time consumption statistics.
Usage data returned by GET /esim/{iccid} may be cached. Use this endpoint when you need the latest data directly from the network provider.

​
Path Parameters

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

​
When to Use

Refresh usage when:
  • User views their eSIM details and expects current data
  • Implementing usage alerts or thresholds
  • Before displaying low-data warnings
  • Monitoring active eSIMs in real-time

​
Response

Returns the full eSIM details (same as GET /esim/{iccid}) with freshly fetched usage data.

​
Example Usage

const iccid = '8910300000000012345';

// Refresh and get latest data
const response = await fetch(`https://api.fyatu.com/api/v3/esim/${iccid}/refresh`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

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

// Now usage data is fresh from provider
console.log(`Fresh usage data (updated just now):`);
console.log(`Data used: ${data.usage.data.usedMb}MB`);
console.log(`Remaining: ${data.usage.data.remainingMb}MB`);
console.log(`${data.usage.data.percentUsed}% consumed`);

// Check if low on data
if (data.usage.data.percentUsed > 80) {
  console.log('Warning: eSIM is low on data!');
  // Suggest top-up
}

​
Rate Limiting

To protect against excessive provider API calls, refresh requests are limited. Avoid calling refresh more than once per minute per eSIM.

​
Error Handling

Error CodeHTTPDescription
ESIM_NOT_FOUND404eSIM doesn’t exist or not owned by you
REFRESH_FAILED400Failed to fetch data from provider
SERVICE_UNAVAILABLE503Provider service temporarily unavailable

​
Best Practices

  1. Cache Results: Store the refreshed data and use it for subsequent displays
  2. Throttle Requests: Limit refresh to once per minute per eSIM
  3. Background Updates: Refresh periodically rather than on every page view
  4. Error Handling: Fall back to cached data if refresh fails

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

eSIM data refreshed successfully

​
success
boolean
Example:

true

​
status
integer
Example:

200

​
message
string
​
data
object
​
meta
object