eSIMs · Objects

The eSIM package object

An eSIM package is a data plan you can sell: its data allowance, validity, destination, network operator and the prices for your agency.

The catalog returns it with the supplier's country and operator facts flattened into country_* and operator_* keys.

Four amounts describe the price. price is the base price before your commission, total_price and retail_price are what you charge the traveler, and balance_debit_amount is what is debited from your balance when you order. Read the eSIM pricing guide before you compute anything from them.

Example

{
  "id": "france-in-7days-1gb",
  "package_id": "france-in-7days-1gb",
  "type": "sim",
  "price": 402.5,
  "base_price": 402.5,
  "amount": 1024,
  "day": 7,
  "is_unlimited": false,
  "title": "1 GB - 7 days",
  "is_fair_usage_policy": false,
  "fair_usage_policy": null,
  "data": "1 GB",
  "voice": null,
  "text": null,
  "country_name": "France",
  "country_code": "FR",
  "country_slug": "france",
  "country_image_url": "https://cdn-revamp.airalo.com/images/9753dedb-d495-47cf-b6e4-82e555564743.png",
  "operator_name": "KPN France Data only",
  "operator_id": 1704,
  "operator_style": "dark",
  "operator_gradient_start": "#F1D4FB",
  "operator_gradient_end": "#EEC0FF",
  "operator_type": "local",
  "operator_is_prepaid": false,
  "operator_esim_type": "Prepaid",
  "operator_warning": null,
  "operator_apn_type": "automatic",
  "operator_is_roaming": true,
  "operator_info": [
    "Data-only eSIM.",
    "Rechargeable online with no expiry."
  ],
  "operator_image_url": "https://cdn-revamp.airalo.com/images/01b47d41-fbb4-4032-8f5a-d1ca6a0f3688.png",
  "operator_plan_type": "data",
  "operator_activation_policy": "first-usage",
  "operator_is_kyc_verify": false,
  "operator_rechargeability": true,
  "operator_other_info": "Covers metropolitan (mainland) France and Corsica. Does not include overseas territories (Guadeloupe, Martinique, Reunion, ...",
  "operator_coverages": [
    {
      "name": "FR",
      "code": "FR",
      "networks": [
        {
          "name": "Orange",
          "types": [
            "5G"
          ]
        }
      ]
    }
  ],
  "operator_apn": {
    "ios": {
      "apn_type": "automatic",
      "apn_value": null
    },
    "android": {
      "apn_type": "automatic",
      "apn_value": null
    }
  },
  "is_regional": false,
  "is_global": false,
  "retail_price": 468.84,
  "total_price": 468.84,
  "balance_debit_amount": 418.6,
  "b2b_price": 418.6,
  "agency_commission": "12 %",
  "commission_rate": 12,
  "currency": "DZD",
  "supplier_currency": "USD",
  "exchange_rate": 250
}

Attributes

idstringdeprecated

Legacy name, still accepted. Use package_id instead.

Package id. Send it as package_id when you create an order. Always read it from the catalog: ids change when suppliers change their offer. The older name of package_id: same value, use package_id.

package_idstring

Package id. Send it as package_id when you create an order. Always read it from the catalog: ids change when suppliers change their offer. The snake_case twin of id, with the same value: use this name.

typestring

Always sim: the package is sold as a new eSIM.

pricenumberdeprecated

Legacy name, still accepted. Use base_price instead.

Base price in your agency currency, before your commission. It is not what is debited from your balance: use balance_debit_amount. The older name of base_price: same value, use base_price.

base_pricenumber

Base price in your agency currency, before your commission. It is not what is debited from your balance: use balance_debit_amount. The snake_case twin of price, with the same value: use this name.

amountinteger

Data allowance in megabytes. 0 means unlimited: check is_unlimited.

dayinteger

Validity in days. It starts at the first use of the eSIM or at installation, see operator_activation_policy.

is_unlimitedboolean

true for unlimited-data packages.

titlestring

Label of the package: data allowance and validity, in the language of the request.

is_fair_usage_policyboolean

Whether a fair usage policy applies. A boolean on limited packages and 0 or 1 on unlimited ones: treat 0 as false and 1 as true.

fair_usage_policystringnullable

The fair usage terms, for example the speed after a daily threshold. Null when no policy applies.

datastring

Data allowance as text, for example 1 GB or Unlimited.

voiceintegernullable

Voice minutes included. Null for data-only packages.

textintegernullable

SMS included. Null for data-only packages.

country_namestring

Destination country or region name, in the language of the request.

country_codestring

Destination country code (ISO 3166-1 alpha-2). An empty string for regional and worldwide bundles, whose country_slug is the region, for example europe.

country_slugstring

Destination slug. Send it as the country filter of the catalog.

country_image_urlstringnullable

Flag or destination image, for display.

operator_namestring

Name of the mobile network operator or brand the package runs on.

operator_idinteger

Identifier of the operator.

operator_stylestringnullable

Display hint: light or dark text on the operator's colors.

operator_gradient_startstringnullable

First color of the operator's gradient, as a hex value.

operator_gradient_endstringnullable

Second color of the operator's gradient, as a hex value.

operator_typestring

Scope of the package: local for one country, global for regional and worldwide bundles. There is no regional value.

One of local, global.

operator_is_prepaidboolean

Whether the underlying plan is prepaid.

operator_esim_typestring

Type of the plan, for example Prepaid.

operator_warningstringnullable

A caution to show the traveler before the sale. Null when there is none.

operator_apn_typestring

automatic or manual: whether the APN is configured by the eSIM profile or entered by the traveler.

operator_is_roamingboolean

Whether the package works through roaming rather than a local profile.

operator_infoarray of string

Short facts about the network, the technology and whether the eSIM can be recharged.

operator_image_urlstringnullable

Logo of the operator.

operator_plan_typestring

Kind of plan, for example data for a data-only plan.

operator_activation_policystring

When validity starts, for example first-usage: at the first connection, not at purchase.

operator_is_kyc_verifyboolean

Whether the destination requires identity verification for this operator. Rare.

operator_rechargeabilityboolean

Whether the eSIM can be topped up, see the topup guide.

operator_other_infostringnullable

Longer notes on coverage and exclusions, for example territories that are not covered.

operator_coveragesarray of object

Countries covered, with their networks.

ShowHide 3 attributes

namestring

Country or area name as the supplier lists it.

codestring

Country code (ISO 3166-1 alpha-2) or area code.

networksarray of object

Networks the eSIM can use in this country, with their technologies.

ShowHide 2 attributes

namestring

Name of the mobile network.

typesarray of string

Technologies the network offers in this country.

operator_apnobjectnullable

APN settings per operating system.

ShowHide 2 attributes

iosobject

Access point name (APN) settings for one operating system.

ShowHide 2 attributes

apn_typestring

automatic when the device configures the access point name by itself, manual when the traveler has to enter it.

apn_valuestringnullable

The access point name to enter on a manual setup; null or N/A when none is needed.

androidobject

Access point name (APN) settings for one operating system.

ShowHide 2 attributes

apn_typestring

automatic when the device configures the access point name by itself, manual when the traveler has to enter it.

apn_valuestringnullable

The access point name to enter on a manual setup; null or N/A when none is needed.

is_regionalboolean

Always false. Regional bundles are global packages: check operator_type.

is_globalboolean

true when operator_type is global.

retail_pricenumber

The price to charge the traveler, in your agency currency. Equal to total_price.

total_pricenumber

The price to charge the traveler, in your agency currency. It includes your commission.

balance_debit_amountnumberdeprecated

Legacy name, still accepted. Use b2b_price instead.

The amount debited from your agency balance when you order this package. total_price minus this amount is your commission. The older name of b2b_price: same value, use b2b_price.

b2b_pricenumber

The amount debited from your agency balance when you order this package. total_price minus this amount is your commission. The snake_case twin of balance_debit_amount, with the same value: use this name.

agency_commissionstring

Your commission rate as text, for example 12 %; 0 % for contracted corporate agencies. Bookings carry the commission as an amount.

commission_ratenumber

Your commission rate as a number: 12 for a standard agency, 0 for a contracted corporate agency. Same rate as agency_commission.

currencystring

Currency of every amount on the package: the settlement currency of your agency.

supplier_currencystring

Currency the supplier prices the package in.

exchange_ratenumber

Rate used to convert supplier_currency to your agency currency.

{ "id": "france-in-7days-1gb", "package_id": "france-in-7days-1gb", "type": "sim", "price": 402.5, "base_price": 402.5, "amount": 1024, "day": 7, "is_unlimited": false, "title": "1 GB - 7 days", "is_fair_usage_policy": false, "fair_usage_policy": null, "data": "1 GB", "voice": null, "text": null, "country_name": "France", "country_code": "FR", "country_slug": "france", "country_image_url": "https://cdn-revamp.airalo.com/images/9753dedb-d495-47cf-b6e4-82e555564743.png", "operator_name": "KPN France Data only", "operator_id": 1704, "operator_style": "dark", "operator_gradient_start": "#F1D4FB", "operator_gradient_end": "#EEC0FF", "operator_type": "local", "operator_is_prepaid": false, "operator_esim_type": "Prepaid", "operator_warning": null, "operator_apn_type": "automatic", "operator_is_roaming": true, "operator_info": [ "Data-only eSIM.", "Rechargeable online with no expiry." ], "operator_image_url": "https://cdn-revamp.airalo.com/images/01b47d41-fbb4-4032-8f5a-d1ca6a0f3688.png", "operator_plan_type": "data", "operator_activation_policy": "first-usage", "operator_is_kyc_verify": false, "operator_rechargeability": true, "operator_other_info": "Covers metropolitan (mainland) France and Corsica. Does not include overseas territories (Guadeloupe, Martinique, Reunion, ...", "operator_coverages": [ { "name": "FR", "code": "FR", "networks": [ { "name": "Orange", "types": [ "5G" ] } ] } ], "operator_apn": { "ios": { "apn_type": "automatic", "apn_value": null }, "android": { "apn_type": "automatic", "apn_value": null } }, "is_regional": false, "is_global": false, "retail_price": 468.84, "total_price": 468.84, "balance_debit_amount": 418.6, "b2b_price": 418.6, "agency_commission": "12 %", "commission_rate": 12, "currency": "DZD", "supplier_currency": "USD", "exchange_rate": 250 }

Attributes

idstringdeprecated

Legacy name, still accepted. Use package_id instead.

package_idstring

typestring

Always sim: the package is sold as a new eSIM.

pricenumberdeprecated

Legacy name, still accepted. Use base_price instead.

Base price in your agency currency, before your commission. It is not what is debited from your balance: use balance_debit_amount. The older name of base_price: same value, use base_price.

base_pricenumber

amountinteger

Data allowance in megabytes. 0 means unlimited: check is_unlimited.

dayinteger

Validity in days. It starts at the first use of the eSIM or at installation, see operator_activation_policy.

is_unlimitedboolean

true for unlimited-data packages.

titlestring

Label of the package: data allowance and validity, in the language of the request.

is_fair_usage_policyboolean

Whether a fair usage policy applies. A boolean on limited packages and 0 or 1 on unlimited ones: treat 0 as false and 1 as true.

fair_usage_policystringnullable

The fair usage terms, for example the speed after a daily threshold. Null when no policy applies.

datastring

Data allowance as text, for example 1 GB or Unlimited.

voiceintegernullable

Voice minutes included. Null for data-only packages.

textintegernullable

SMS included. Null for data-only packages.

country_namestring

Destination country or region name, in the language of the request.

country_codestring

Destination country code (ISO 3166-1 alpha-2). An empty string for regional and worldwide bundles, whose country_slug is the region, for example europe.

country_slugstring

Destination slug. Send it as the country filter of the catalog.

country_image_urlstringnullable

Flag or destination image, for display.

operator_namestring

Name of the mobile network operator or brand the package runs on.

operator_idinteger

Identifier of the operator.

operator_stylestringnullable

Display hint: light or dark text on the operator's colors.

operator_gradient_startstringnullable

First color of the operator's gradient, as a hex value.

operator_gradient_endstringnullable

Second color of the operator's gradient, as a hex value.

operator_typestring

Scope of the package: local for one country, global for regional and worldwide bundles. There is no regional value.

One of local, global.

operator_is_prepaidboolean

Whether the underlying plan is prepaid.

operator_esim_typestring

Type of the plan, for example Prepaid.

operator_warningstringnullable

A caution to show the traveler before the sale. Null when there is none.

operator_apn_typestring

automatic or manual: whether the APN is configured by the eSIM profile or entered by the traveler.

operator_is_roamingboolean

Whether the package works through roaming rather than a local profile.

operator_infoarray of string

Short facts about the network, the technology and whether the eSIM can be recharged.

operator_image_urlstringnullable

Logo of the operator.

operator_plan_typestring

Kind of plan, for example data for a data-only plan.

operator_activation_policystring

When validity starts, for example first-usage: at the first connection, not at purchase.

operator_is_kyc_verifyboolean

Whether the destination requires identity verification for this operator. Rare.

operator_rechargeabilityboolean

Whether the eSIM can be topped up, see the topup guide.

operator_other_infostringnullable

Longer notes on coverage and exclusions, for example territories that are not covered.

operator_coveragesarray of object

Countries covered, with their networks.

ShowHide 3 attributes

namestring

Country or area name as the supplier lists it.

codestring

Country code (ISO 3166-1 alpha-2) or area code.

networksarray of object

Networks the eSIM can use in this country, with their technologies.

ShowHide 2 attributes

namestring

Name of the mobile network.

typesarray of string

Technologies the network offers in this country.

operator_apnobjectnullable

APN settings per operating system.

ShowHide 2 attributes

iosobject

Access point name (APN) settings for one operating system.

ShowHide 2 attributes

apn_typestring

automatic when the device configures the access point name by itself, manual when the traveler has to enter it.

apn_valuestringnullable

The access point name to enter on a manual setup; null or N/A when none is needed.

androidobject

Access point name (APN) settings for one operating system.

ShowHide 2 attributes

apn_typestring

automatic when the device configures the access point name by itself, manual when the traveler has to enter it.

apn_valuestringnullable

The access point name to enter on a manual setup; null or N/A when none is needed.

is_regionalboolean

Always false. Regional bundles are global packages: check operator_type.

is_globalboolean

true when operator_type is global.

retail_pricenumber

The price to charge the traveler, in your agency currency. Equal to total_price.

total_pricenumber

The price to charge the traveler, in your agency currency. It includes your commission.

balance_debit_amountnumberdeprecated

Legacy name, still accepted. Use b2b_price instead.

The amount debited from your agency balance when you order this package. total_price minus this amount is your commission. The older name of b2b_price: same value, use b2b_price.

b2b_pricenumber

agency_commissionstring

Your commission rate as text, for example 12 %; 0 % for contracted corporate agencies. Bookings carry the commission as an amount.

commission_ratenumber

Your commission rate as a number: 12 for a standard agency, 0 for a contracted corporate agency. Same rate as agency_commission.

currencystring

Currency of every amount on the package: the settlement currency of your agency.

supplier_currencystring

Currency the supplier prices the package in.

exchange_ratenumber

Rate used to convert supplier_currency to your agency currency.