airalo-sdk-type

Unofficial TypeScript/JavaScript SDK for the Airalo Partner API

Table of contents

• Installation
• Quick start
• Environments
• API reference
  • Auth
  • Packages
  • Orders
  • eSIMs
  • Balance
  • Notifications
  • Misc
• Response format
• All methods
• Contributing
• License

Installation

npm install airalo-sdk-type
# or
yarn add airalo-sdk-type

Quick start

import Airalo from "airalo-sdk-type";

// 1. Point to sandbox or production
Airalo.setHost("https://sandbox-partners-api.airalo.com");

// 2. Authenticate — token is stored automatically
await Airalo.auth.TOKEN({
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET"
});

// 3. Fetch available packages
const { data } = await Airalo.Package.Packages();
console.log(data);

// 4. Place an order
const order = await Airalo.Order.SubmitOrder({
  quantity: "1",
  package_id: "chinacom-7days-1gb"
});
console.log(order.data?.sims[0].qrcode);

Environments

| Environment | Base URL | | ----------- | ----------------------------------------- | | Sandbox | https://sandbox-partners-api.airalo.com | | Production | https://partners-api.airalo.com |

// Sandbox (default)
Airalo.setHost("https://sandbox-partners-api.airalo.com");

// Production
Airalo.setHost("https://partners-api.airalo.com");

// Enable request/response logging
Airalo.setLogger(true);

API reference

Auth

// Fetch and store an access token
await Airalo.auth.TOKEN({
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET"
});

Packages

// List all available packages
const all = await Airalo.Package.Packages();

// Filter by country, page, and limit
const jp = await Airalo.Package.Packages({
  "filter[country]": "JP",
  limit: 10,
  page: 1
});

Orders

// Place a synchronous order — response includes SIM + QR code immediately
const order = await Airalo.Order.SubmitOrder({
  quantity: "1",
  package_id: "chinacom-7days-1gb",
  type: "sim", // optional, defaults to "sim"
  description: "My order", // optional
  brand_settings_name: "MyBrand" // optional, null = unbranded
});

// Place an asynchronous order — result is delivered via webhook
await Airalo.Order.SubmitOrderAsync({
  quantity: "1",
  package_id: "chinacom-7days-1gb",
  webhook_url: "https://myapp.com/webhook",
  to_email: "[email protected]", // optional
  sharing_option: ["link", "pdf"], // optional, required if to_email is set
  copy_address: ["[email protected]"] // optional
});

// Place a top-up order for an existing eSIM
await Airalo.Order.SubmitTopUpOrder({
  package_id: "bonbon-mobile-30days-3gb-topup",
  iccid: "8934000000000087299",
  description: "Top-up" // optional
});

// List orders with filters
const orders = await Airalo.Order.GetOrderList({
  "filter[order_status]": "completed", // completed | failed | refunded
  "filter[iccid]": "89343",
  "filter[code]": "20221021-003188",
  "filter[created_at]": "2024-01-01 - 2024-12-31",
  include: "sims,status",
  limit: 20,
  page: 1
});

// Get a single order by ID
const single = await Airalo.Order.GetOrder(731579);

// List all order statuses
const statuses = await Airalo.Order.GetOrderStatuses();

// Get a specific status by slug
const status = await Airalo.Order.GetOrderStatusBySlug("completed");

eSIMs

// List eSIMs with optional filters
const sims = await Airalo.Sims.GetSimList({
  "filter[iccid]": "8910300000",
  "filter[created_at]": "2024-01-01 - 2024-12-31",
  include: "order,order.status,share",
  limit: 10,
  page: 1
});

// Get a single eSIM by ICCID
const sim = await Airalo.Sims.GetSim("8910300000033289733");

// Get installation instructions (QR + manual)
const instructions = await Airalo.Sims.GetSimInstructions(
  "8910300000033289733"
);

// Get current data usage
const usage = await Airalo.Sims.GetDataUsage("8910300000033289733");
// usage.data.remaining  — bytes remaining
// usage.data.total      — total bytes
// usage.data.status     — NOT_ACTIVE | ACTIVE | FINISHED | EXPIRED

// List available top-up packages for an eSIM
const topups = await Airalo.Sims.GetTopUpPackageList("8910300000033289733");

// Get package history for an eSIM
const history = await Airalo.Sims.GetSimPackageHistory("8910300000033289733");

// Update the brand name shown on an eSIM
await Airalo.Sims.UpdateSimBrand("8910300000033289733", "MyBrand");

Balance

const balance = await Airalo.Balance.GetBalance();
console.log(balance.data?.balances.availableBalance.amount);
console.log(balance.data?.balances.availableBalance.currency);

Notifications

// Opt in to low-data webhook notifications
await Airalo.Notification.NotificationOptIn({
  type: "webhook_low_data",
  webhook_url: "https://myapp.com/webhook"
});

// Opt in to credit-limit notifications with threshold levels (%)
await Airalo.Notification.NotificationOptIn({
  type: "webhook_credit_limit",
  webhook_url: "https://myapp.com/webhook",
  levels: [50, 70, 80, 90]
});

// Opt out
await Airalo.Notification.NotificationOptOut({
  type: "webhook_low_data" // email_low_data | email_credit_limit | webhook_low_data | webhook_credit_limit
});

// Get current notification settings
const settings = await Airalo.Notification.GetNotification();

// Simulate a webhook event (sandbox only)
await Airalo.Notification.SimulateWebhook({
  event: "low_data_notification",
  type: "expire_1",
  iccid: "8997212330099025334"
});

Misc

// List eSIM-compatible devices
const devices = await Airalo.Misc.GetCompatibleDevices();

// Create an eSIM voucher
const voucher = await Airalo.Misc.CreateEsimVoucher({
  package_id: "chinacom-7days-1gb",
  quantity: 1
});

Response format

Every method returns an ApiResult<T> object:

// Success
{
  success: true,
  data: T,
  message: "Амжилттай."
}

// Error
{
  success: false,
  data: null,
  message: "Error message from API"
}

Check result.success before accessing result.data:

const result = await Airalo.Order.SubmitOrder({
  quantity: "1",
  package_id: "chinacom-7days-1gb"
});

if (result.success) {
  console.log(result.data.sims[0].qrcode_url);
} else {
  console.error(result.message);
}

All methods

| Module | Method | Description | | -------------- | ---------------------- | --------------------------------------- | | auth | TOKEN | Fetch and store access token | | Package | Packages | List packages (filterable by country) | | Order | SubmitOrder | Place a synchronous order | | Order | SubmitOrderAsync | Place an asynchronous order via webhook | | Order | SubmitTopUpOrder | Top up an existing eSIM | | Order | GetOrderList | List orders with filters | | Order | GetOrder | Get a single order by ID | | Order | GetOrderStatuses | List all order statuses | | Order | GetOrderStatusBySlug | Get a single status by slug | | Sims | GetSimList | List eSIMs with filters | | Sims | GetSim | Get a single eSIM by ICCID | | Sims | GetSimInstructions | Get installation instructions | | Sims | GetDataUsage | Get current data usage | | Sims | GetTopUpPackageList | List available top-up packages | | Sims | GetSimPackageHistory | Get package history | | Sims | UpdateSimBrand | Update eSIM brand name | | Balance | GetBalance | Get account balance | | Notification | NotificationOptIn | Enable a notification type | | Notification | NotificationOptOut | Disable a notification type | | Notification | GetNotification | Get current notification settings | | Notification | SimulateWebhook | Simulate a webhook event (sandbox) | | Misc | GetCompatibleDevices | List eSIM-compatible devices | | Misc | CreateEsimVoucher | Create an eSIM voucher |

Contributing

Pull requests are welcome. For major changes, please open an issue first.

git clone https://github.com/togtokh-dev/airalo.git
cd airalo
npm install
npm test

License

ISC © Buyantogtokh

This is an unofficial SDK and is not affiliated with or endorsed by Airalo.