# airalo-sdk-type > Unofficial TypeScript/JavaScript SDK for the [Airalo Partner API](https://partners-api.airalo.com) [![npm version](https://img.shields.io/npm/v/airalo-sdk-type)](https://www.npmjs.com/package/airalo-sdk-type) [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/) --- ## Table of contents - [Installation](#installation) - [Quick start](#quick-start) - [Environments](#environments) - [API reference](#api-reference) - [Auth](#auth) - [Packages](#packages) - [Orders](#orders) - [eSIMs](#esims) - [Balance](#balance) - [Notifications](#notifications) - [Misc](#misc) - [Response format](#response-format) - [All methods](#all-methods) - [Contributing](#contributing) - [License](#license) --- ## Installation ```bash npm install airalo-sdk-type # or yarn add airalo-sdk-type ``` --- ## Quick start ```typescript 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` | ```typescript // 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 ```typescript // Fetch and store an access token await Airalo.auth.TOKEN({ client_id: "YOUR_CLIENT_ID", client_secret: "YOUR_CLIENT_SECRET" }); ``` --- ### Packages ```typescript // 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 ```typescript // 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: "user@example.com", // optional sharing_option: ["link", "pdf"], // optional, required if to_email is set copy_address: ["cc@example.com"] // 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 ```typescript // 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 ```typescript const balance = await Airalo.Balance.GetBalance(); console.log(balance.data?.balances.availableBalance.amount); console.log(balance.data?.balances.availableBalance.currency); ``` --- ### Notifications ```typescript // 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 ```typescript // 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` object: ```typescript // Success { success: true, data: T, message: "Амжилттай." } // Error { success: false, data: null, message: "Error message from API" } ``` Check `result.success` before accessing `result.data`: ```typescript 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. ```bash git clone https://github.com/togtokh-dev/airalo.git cd airalo npm install npm test ``` --- ## License [ISC](https://opensource.org/licenses/ISC) © Buyantogtokh > This is an **unofficial** SDK and is not affiliated with or endorsed by Airalo.