Subscription Containers

Fees for Subscription Containers are now reduced. Refer to the Pricing & Fee Schedule for more information.

Subscription containers are a feature of plan01s and plan-US SIM cards and eSIMs which allow you to add extra subscription plans to the same SIM. These optional subscriptions allow you to unlock lower data rates in specific regions, or extend coverage to more countries and networks.

By default, each plan01s or plan-US SIM is preprogrammed with an operator profile from Soracom, which includes a corresponding plan01s or plan-US subscription plan. When your device connects to a cellular network, it uses the information stored in this subscription plan, such as Subscriber Identity (IMSI) and authentication keys, to authenticate itself.

Subscription containers

In addition to the default plan01s or plan-US subscription, the Soracom profile is capable of storing additional subscription plans. Adding more subscriptions means that your SIM will have additional sets of IMSIs and their corresponding keys, which will allow your device to connect to more networks in more countries, or to access cheaper data rates.

Switching between subscription plans is handled automatically by an applet built into the Soracom profile. Your device does not need any special configuration, and the SIM will automatically pick the best subscription based on the country where your device is located.

The data for each subscription (IMSI, authentication keys, etc.) is packaged into a subscription container, which can then be securely sent to your device and installed on the SIM through a simple Over-The-Air (OTA) update.

Delivery

Subscription containers are delivered wirelessly to plan01s and plan-US SIMs through an OTA update. As long as your device is connected using a plan01s or plan-US SIM, you can add a subscription container to the SIM no matter where it's located.

Depending on your device's cellular network compatibility, adding a subscription container to your SIM can cause connectivity problems. Refer to the Requirements and Limitations sections below.

Subscription download

Subscriptions can be added by simply logging into the Soracom User Console, selecting a plan01s or plan-US SIM, and adding a subscription. Soracom takes care of packaging subscription details (such as IMSI and authentication keys) into a subscription container, and sending the container to your device.

Once your device receives the container, it is automatically added to the plan01s or plan-US SIM Soracom profile. The profile applet will then check if your device is currently located in a country supported by the new subscription, and if so, automatically switch subscriptions.

Application Compatibility

To reduce the complexity of managing multiple subscriptions, Soracom automatically synchronizes subscription settings for all subscriptions within a particular SIM. For example, if you give your plan01s or plan-US SIM a Name, change its Speed Class, or add custom Tags, these settings will also be updated for other subscriptions in the SIM. This way, you do not need to worry about updating settings for each subscription separately.

This synchronization also applies to Group assignments and any settings that you configure in the group. If your SIM is added to a group where Custom DNS, Metadata Service, or another option is enabled, your device will also receive those settings when it connects to a network using a different subscription container.

Since groups are where you can enable other Soracom platform services, such as Beam, Funnel, Funk, and Harvest, your device will also have access to the same service configurations when it uses its other subscriptions. That way, if you build your application using the default plan01s or plan-US subscription and later decide to add another subscription to expand coverage or reduce data fees, you do not need to update any of your group assignments or configurations.

Some Soracom services use or report the subscription IMSI, such as appending the IMSI to a topic name when using Beam MQTT, adding the IMSI to a request header, payload, or token claim when using Beam HTTP, Funnel, or Endorse, or capturing data and viewing it with Harvest Data and Lagoon. These options allow you to uniquely identify which device the data is coming from. Although the SIM will use a different IMSI when it connects to a network using a different subscription container, Soracom will automatically find the IMSI of the original plan01s or plan-US subscription and use this primary IMSI instead. With this behavior, regardless of which subscription your device is currently using to connect, it will always be identified by its plan01s or plan-US IMSI, so that you do not need to re-associate your data.

If your application uses the subscription IMSI independently of Soracom services, such as configuring your device to check and report the IMSI directly to your server, the primary IMSI association will not occur.


Available Subscriptions

The following subscriptions are available and can be added to any plan01s SIM:

Optional Subscriptions
Plan planP1 planX1 planX2 planX3 plan-US-max
Pricing Pay-As-You-Go Pay-As-You-Go with bundled data Pay-As-You-Go
Bundled Data 5MB
Coverage Asia Pacific *1 Japan (au/KDDI) Global *1 United States *1
Connectivity 2G, 3G, 4G/LTE *2 4G/LTE 4G/LTE, 5G 2G, 3G, 4G/LTE, LTE Cat-M1 *2 2G, 4G/LTE, LTE Cat-M1 *2
Form Factors Over-The-Air (OTA) update
Data
SMS MT-SMS only *3 Limited *4
USSD
Voice

*1 - Refer to the Supported Carriers documentation for carrier information.
*2 - Actual network availability varies by country and local operator.
*3 - Mobile Terminated SMS, or SMS delivered from Soracom to a device.
*4 - Only supported between plan-US-max SIMs.

The following subscriptions are available and can be added to any plan-US SIM:

Optional Subscriptions
Plan plan-US-max plan-US-NA
Pricing Pay-As-You-Go with bundled data
Bundled Data Same as plan-US
Coverage United States*5 North America*5
Connectivity 2G, 4G/LTE *6 2G, 3G, 4G/LTE *6
Form Factors Over-The-Air (OTA) update
Data
SMS Limited *7 MT-SMS only *8
USSD
Voice

*5 - Refer to the Supported Carriers documentation for carrier information.
*6 - Actual network availability varies by country and local operator.
*7 - Only supported between plan-US-max SIMs.
*8 - Mobile Terminated SMS, or SMS delivered from Soracom to a device.

Subscription Priority

Since plan01s, planP1, planX1, planX2, planX3, and plan-US-max subscriptions have overlapping coverage, your device will have more than one subscription that can be used to connect to local networks. The built-in Soracom profile applet will check which country your device is located in and automatically activate the best subscription available for that country. The following table describes which subscription is activated based on what subscriptions you have added to your SIM and which country or region you are connecting from:

Device Location
Subscriptions in SIM APAC *9 Japan *10, *11 United States *12 Rest Of World *13
plan01s only plan01s plan01s plan01s plan01s
plan01s + plan-US-max plan01s plan01s plan-US-max plan01s
plan01s + planP1 planP1 planP1 planP1 plan01s
plan01s + planX1 plan01s planX1 plan01s plan01s
plan01s + planX2 plan01s planX2 plan01s plan01s
plan01s + planP1 + planX1 planP1 planX1 planP1 plan01s
plan01s + planP1 + planX2 planP1 planX2 planP1 plan01s
plan01s + planX3 planX3 planX3 planX3 planX3 or plan01s
plan01s + planX3 + (other) planX3 or planP1 planX3 planX3 or plan-US-max planX3 or plan01s

*9 - Actual coverage in APAC depends on which subscription is activated; Refer to the Supported Carriers documentation for carrier information.
*10 - Connectivity in Japan is provided by NTT Docomo and SoftBank for plan01s; by SoftBank only for planP1; by SoftBank and au/KDDI (plus NTT Docomo by request) for planX1; by au/KDDI only for planX2; and by Softbank and NTT Docomo for planX3.
*11 - Configurations that include both planX1 and planX2 subscriptions are not shown. If your SIM includes both of these subscriptions, planX2 will be prioritized.
*12 - plan-US-max coverage will always take precedence over other plans in the United States.
*13 - Configurations that include planX3 will automatically prioritize planX3wherever coverage is available. In some cases, this may result in reduced coverage compared to plan01s. Refer to the Supported Carriers documentation for carrier information.

Similarly, when using plan-US with plan-US-NA and plan-US-max subscriptions, the plan that is being used will differ based on country and network.

Device Network/Location
United States Canada & Mexico
Subscriptions in SIM US Cellular, AT&T, and regional carriers Verizon T-Mobile Rogers or AT&T Mexico
plan-US only plan-US
plan-US + plan-US-max plan-US plan-US-max
plan-US + plan-US-NA plan-US plan-US-NA
plan-US + plan-US-max + plan-US-NA plan-US plan-US-max plan-US-NA

Requirements

In order to add a subscription container to your plan01s or plan-US SIM, your device must support the following requirements:

Limitations

Before adding a subscription to your plan01s or plan-US SIM, please be aware of the following limitations:


Adding a Subscription

Adding a subscription will incur fees. Refer to the Pricing & Fee Schedule for more information.

To add a subscription to a SIM:

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to manage.

  3. Click the Actions menu, then select Add subscription....

    https://console.soracom.io

    Add subscription

  4. Click the for the subscription you want to add, then click Add Subscription.

    https://console.soracom.io

    Add subscription to SIM

  5. A dialog box will appear asking you to confirm your choice. Please read and aknowledge the warnings associated with adding a subscription container, then click Add subscription.

    Confirm

    Soracom will then begin the OTA update process.

In most cases, delivery and activation of a new subscription container will take approximately 1-2 minutes.

Delivery Status

While using the new SIM Management screen, each SIM will display which subscription containers have been added to the SIM:

https://console.soracom.io

Subscription status

For each SIM, the IMSI column will contain the plan01s or plan-US IMSI (the primary IMSI), as well as the IMSIs of the additional subscriptions below it. Similarly, the Subscription column will indicate the names of the subscriptions that have been added to the SIM.

When adding a planP1, planX1, planX2, planX3, plan-US-max, or plan-US-NA subscription to a SIM, a subscription delivery status may appear in parentheses next to the subscription name. The following table describes the meaning of each status:

Status Meaning
shipped Soracom has prepared the subscription container and is waiting for your device to come online to start the OTA update, or Soracom has sent the OTA update and is waiting for the SIM to confirm its receipt.
delivered The SIM has confirmed receiving the OTA update; Soracom is now waiting for the SIM to install the subscription container.
ready The subscription container was successfully installed, and your device can now use it.
failed There was an error delivering the subscription container to your device.
(no status) Your device has successfully connected to a network using the new subscription container.

If you no longer see a status next to the additional subscriptions, this means that your device has successfully started to use the new subscription. From now on, you can refer to the Subscriber Status to see the current online or offline status of your SIMs.

Subscription Delivery Failures

The delivery of an additional subscription occurs via an Over-The-Air (OTA) update utilizing several SMS messages. If a cellular session becomes unstable or is ended while an OTA update is in progress, the OTA update will be interrupted. This can potentially result in the subscription container being stuck in a shipped or delivered status.

To retry the OTA update process, reboot the device in a location with good reception at least 24 hours after the device was last online. Up to 3 retries will be performed for each additional subscription.

After the retry begins, the server will repeatedly attempt to send the OTA update SMS messages according to the specifications in SMS failure . However, if the cellular session becomes unstable or is ended while the OTA update is in progress, the OTA update will be interrupted again and another retry will have to be performed.

If the third OTA update retry fails, no further OTA updates will be attempted. In these cases, please contact Soracom support for additional assistance.


Programmatic Usage

In addition to adding Subscription Containers from the User Console, you can also perform the same configuration programmatically, allowing you to integrate automated control of your SIM's Subscription Containers inside your application.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the addSubscription API to add a subscription container to an Air SIM or Arc Virtual SIM:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "enable": true,
>        "subscription": "plan-US-NA",
>        "type": "cellular"
>      }' \
>  https://g.api.soracom.io/v1/sims/<SIM_ID>/profiles/<ICCID>/add_subscription

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to add a subscription container to an Air SIM or Arc Virtual SIM:

soracom sims add-subscription --sim-id <SIM-ID> --iccid <ICCID> --body '<SUBSCRIPTION-DETAILS>' --coverage-type g

Here, the JSON object of the request body from the API example above should be passed in to the --body parameter.