Usage Check

Check real-time data usage for one or more eSIM profiles.

Check Usage

Endpoint: POST /api/v1/open/esim/usage/query

Request Parameters

Name	Type	Required	Description
`esimTranNoList`	Array	Required	List of eSIM transaction numbers to check

Example Request - Single eSIM

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/usage/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "esimTranNoList": ["25030303480009"]
}'

Example Request - Multiple eSIMs

curl --location --request POST 'https://your-api-domain.com/api/v1/open/esim/usage/query' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "esimTranNoList": [
        "25030303480009",
        "25030303480010",
        "25030303480011"
    ]
}'

Response Parameters

Name	Type	Description
`success`	Boolean	`true` = succeeded, `false` = failed
`errorCode`	String	Error code when failed
`errorMsg`	String	Error message
`obj`	Array	List of usage data

Usage Object

Field	Type	Description	Example
`esimTranNo`	String	eSIM transaction number	`25030303480009`
`totalVolume`	Long	Total data in bytes	`1073741824`
`usedVolume`	Long	Used data in bytes	`524288000`
`remainVolume`	Long	Remaining data in bytes	`549453824`

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": [
        {
            "esimTranNo": "25030303480009",
            "totalVolume": 1073741824,
            "usedVolume": 524288000,
            "remainVolume": 549453824
        }
    ]
}

Converting Data Values

Data values are in bytes:

function formatBytes(bytes) {
    if (bytes === 0) return '0 B';
    const k = 1024;
    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
    const i = Math.floor(Math.log(bytes) / Math.log(k));
    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}
 
// Example usage
const usage = {
    usedVolume: 524288000,      // 500 MB
    totalVolume: 1073741824,    // 1 GB
    remainVolume: 549453824     // ~524 MB
};
 
console.log(`Used: ${formatBytes(usage.usedVolume)}`);        // "500 MB"
console.log(`Total: ${formatBytes(usage.totalVolume)}`);      // "1 GB"
console.log(`Remaining: ${formatBytes(usage.remainVolume)}`); // "524 MB"

Batch Usage Check

For efficient monitoring, check multiple eSIMs in a single request:

async function checkBatchUsage(esimTranNoList) {
    const response = await fetch('https://your-api-domain.com/api/v1/open/esim/usage/query', {
        method: 'POST',
        headers: {
            'RT-AccessCode': 'YOUR_ACCESS_CODE',
            'RT-SecretKey': 'YOUR_SECRET_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ esimTranNoList })
    });
    const data = await response.json();
    return data.obj;
}

Use Cases

Customer dashboard - Display real-time usage to customers
Low data alerts - Notify when usage exceeds threshold
Usage reports - Generate usage reports for billing
Expiry warnings - Alert customers before eSIM expires

Best Practices

Cache wisely - Usage data is updated periodically, cache for 5-15 minutes
Batch requests - Use multiple eSIMs per request to reduce API calls
Handle delays - Usage data may have a delay of up to 24 hours

Send SMS Supported Regions