Subscription Containers

Subscription container functionality was recently released. The information on this page may be subject to change as we improve the service.

Subscription containers are a feature of plan01s 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 SIM is preprogrammed with an operator profile from Soracom, which includes a corresponding plan01s 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 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 SIMs through an OTA update. As long as your device is connected using a plan01s 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 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 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 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 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 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 IMSI, so that you do not need to re-associate your data.

If your application uses the subscription IMSI independantly 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

Currently, the following subscriptions are available and can be added to any plan01s SIM:

Optional Subscriptions
Plan planP1 planX1
Pricing Pay-As-You-Go
Coverage Asia Pacific *1 Japan (au/KDDI)
Connectivity 2G, 3G, 4G/LTE *2 4G/LTE
Form Factors Over-The-Air update
Data
SMS MT-SMS only *3
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

Subscription Priority

Since plan01s, planP1, and planX1 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 *3 Japan *4 Rest Of World
plan01s only plan01s plan01s plan01s
plan01s + planP1 planP1 planP1 plan01s
plan01s + planX1 plan01s planX1 plan01s
plan01s + planP1 + planX1 planP1 planX1 plan01s

*3 - Actual coverage in APAC depends on which subscription is activated; Refer to the Supported Carriers documentation for carrier information
*4 - Connectivity in Japan is provided by NTT docomo for plan01s; by SoftBank for planP1; and by au/KDDI for planX1


Requirements

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

If your device does not support the network type or frequency bands of a particular country or network, it will not fall back to using the original plan01s subscription, and you may experience trouble connecting to a network.

For example, if your 3G-only device is located in Japan and currently connected to NTT docomo's 3G network, and you add a planX1 subscription to your SIM, your device will automatically attempt to switch to the au/KDDI network. Since au/KDDI only provides LTE coverage, your device will no longer be able to connect.

If you have any concerns about compatibility, please feel free to contact us.

Limitations

Before adding a subscription to your plan01s 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. A message should appear offering to let you switch to the new SIM Management console. Click the new SIM Management console link.

    https://console.soracom.io

    Switch to new SIM Management screen

    Compared to the old SIM Management screen, the new screen will include a SIM ID column.

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

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

    https://console.soracom.io

    Add subscription

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

    Add subscription to SIM

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 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 or planX1 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
inStock The subscription container has been prepared; Soracom is waiting for your device to come online in order to deliver it.
shipped Soracom has sent the subscription container to your device via OTA update, and is waiting for the device to install the 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.