Soracom Air for Cellular

Subscription Containers

Subscription containers are a feature of plan01s and plan-US IoT SIM cards and eSIMs which allow you to add additional subscription plans to the same SIM in order to extend coverage to more countries and networks.

By default, each plan01s or plan-US SIM is pre-programmed 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.

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 access cheaper data rates.

Switching between subscription plans is handled automatically by an applet built into the Soracom profile. Here too, your device does not need any special configuration, 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.

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, if so, it automatically switches 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 associated with 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.

Available Subscriptions

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

^{*1 - Refer to the Supported Carriers documentation for carrier information.
*2 - Actual network availability varies by country and local operator.
*3 - Mobile Terminated SMS (SMS delivered from Soracom to a device).
*4 - Supports both MT‑SMS (Mobile Treminated SMS) and MO‑SMS (Mobile Originated SMS). MO‑SMS can only be sent to Unified Endpoint. Specifying any other destination is not supported.}

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

^{*5 - Refer to the Supported Carriers documentation for carrier information.
*6 - Actual network availability varies by country and local operator.
*7 - Supports both MT‑SMS (Mobile Treminated SMS) and MO‑SMS (Mobile Originated SMS). MO‑SMS can only be sent to Unified Endpoint. Specifying any other destination is not supported.
*8 - Mobile Terminated SMS (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:

^{*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 planX3 wherever coverage is available (except in the case of plan-US-max in the United States). 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.

Requirements

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

• SMS functionality (MO-SMS and MT-SMS)

  As the NB-IoT network does not support SMS, SIM cards in NB-IoT devices will be unable to receive Subscription Containers.

• SIM Toolkit (STK) commands

• Network type (such as 2G, 3G, and LTE) and frequency bands for both the original plan01s or plan-US 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 planX2 subscription to your SIM, your device will automatically attempt to switch to the au/KDDI network. Since au/KDDI only provides LTE and 5G coverage for planX2, your device will no longer be able to connect to a network.

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

• Your SIM card is in Active status and in a data session ( Active ONLINE).
  • It is possible to order an additional subscription for a SIM when it is in Active status but not in a data session ( Active OFFLINE), but the OTA process will not occur until the device creates a new data session (ONLINE).

Limitations

Before adding a subscription to your plan01s or plan-US SIM, note 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 or plan-US SIM.
• When one or more subscription containers are added to a plan01s SIM, the SIM will no longer incur the plan01s daily basic fees. However, the SIM will continue to incur the monthly basic fee for each subscription container as follows:
  • For planX1 and planX2, the subscription container monthly basic fee will still be charged even if the SIM is set to Standby or Suspended status.
  • For planP1, planX3, and plan-US-max the subscription container monthly basic fee will be charged when the SIM is set to Active or Inactive status. The monthly basic fee will not be charged when the SIM is in Ready, Standby, or Suspended status.
• When one or more subscription containers are added to a plan-US SIM, an additional subscription fee will be added to the monthly basic fee.
• 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.
• Currently, plan-US-max does not support SMS with SIMs using different plans. 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. There is no support for USSD on plan-US or any of it's subscription containers.
• When a planX3 subscription is added to a plan01s SIM, the planX3 subscription will be prioritized wherever coverage is available. In some cases, planX3 may have access to fewer networks compared to plan01s, which may result in reduced carrier coverage.

Adding a Subscription

Before getting started, ensure that your device meets the requirements for Subscription Container delivery.

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

   

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

   https://console.soracom.io

   

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

   

   Soracom will then begin the OTA update process.

Delivery Status

While using the 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 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:

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 manually initiate a retry of the OTA update process, perform either of the following actions at least 15 minutes after the OTA becomes stuck in shipped or delivered status:

1. Delete the device's session from the User Console.
2. Reboot the device in a location with good reception.

Up to 12 retries will be performed for each additional subscription.

If your SIM becomes stuck in the shipped or delivered status for an extended period, it may have expended its 12 retries. 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.

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

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": "planArc01",
|        "type": "virtual"
|      }' \
|  https://jp.api.soracom.io/v1/sims/<SIM_ID>/profiles/<ICCID>/add_subscription

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

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