Soracom Air for Cellular
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.
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.
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.
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.
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.
Currently, the following subscriptions are available and can be added to any plan01s SIM:
|Coverage||Asia Pacific *1||Japan (au/KDDI)|
|Connectivity||2G, 3G, 4G/LTE *2||4G/LTE||4G/LTE, 5G|
|Form Factors||Over-The-Air update|
|SMS||MT-SMS only *3|
*1 - Refer to the
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
Since plan01s, planP1, planX1, and planX2 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:
|Subscriptions in SIM||APAC *3||Japan *4, *5||Rest Of World|
|plan01s + planP1||planP1||planP1||plan01s|
|plan01s + planX1||plan01s||planX1||plan01s|
|plan01s + planX2||plan01s||planX2||plan01s|
|plan01s + planP1 + planX1||planP1||planX1||plan01s|
|plan01s + planP1 + planX2||planP1||planX2||plan01s|
*3 - Actual coverage in APAC depends on which subscription is activated; Refer to the
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
*5 - Configurations that include both planX1 and planX2 subscriptions are not shown. If your SIM includes both of these subscriptions, planX2 will be prioritized.
In order to add a subscription container to your plan01s SIM, your device must support the following requirements:
- SMS functionality (MO-SMS and MT-SMS)
- SIM Toolkit (STK) commands
- Network type (such as 2G, 3G, and LTE) and frequency bands for both the original plan01s subscription as well as the additional subscription container
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.
Before adding a subscription to your plan01s SIM, please be aware of the following limitations:
- Once a new subscription container is added to a SIM, it cannot be removed. In order to terminate a subscription, you must terminate the corresponding plan01s SIM.
- Changing a plan01s SIM to Standby or Suspended will stop daily fees for the plan01s subscription only. Daily fees for other subscriptions in the SIM still apply.
- Currently, planP1 subscriptions do not support MO-SMS functionality. Your device will not be able to send SMS to the network while it is connected using this subscription, however you can send MT-SMS to your device. Full SMS functionality will still work in other countries when the device is connected using the plan01s subscription.
- Similarly, planP1, planX1, and planX2 subscriptions do not support USSD functionality, and your device will not be able to send USSD while using these subscriptions. USSD functionality will still work in other countries when the device is connected using the plan01s subscription.
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:
Login to the User Console. From the Menu, open the SIM Management screen.
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
Compared to the old SIM Management screen, the new screen will include a SIM ID column.
From the list of subscribers, click the for the SIM you want to manage.
Click the Actions menu, then select Add subscription....https://console.soracom.io
Click the for the subscription you want to add, then click Add Subscription.
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.
While using the new SIM Management screen, each SIM will display which subscription containers have been added to the SIM:
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, planX1, or planX2 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:
||The subscription container has been prepared; Soracom is waiting for your device to come online in order to deliver it.|
||Soracom has sent the subscription container to your device via OTA update, and is waiting for the device to install the container.|
||The subscription container was successfully installed, and your device can now use it.|
||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.