Soracom Air Subscription Containers

Subscription containers are a feature that allows you to add additional subscription plans to a SIM in order to extend coverage to more countries and networks. SIMs that support subscription containers include plan01s, plan-US, and planP1 IoT SIM cards and embedded SIM chips (eSIMs).

By default, each of these SIMs is pre-programmed with an operator profile from Soracom, which includes a primary subscription. When your device connects to a cellular network, it uses the information stored in the primary subscription, such as Subscriber Identity (IMSI) and authentication keys, to authenticate itself.

In addition to the primary subscription, the Soracom profile is capable of storing additional subscriptions. 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 a subscription based on the country where your device is located. Refer to Subscription Priority for the exact rules, as the selected subscription depends on the combination of subscriptions on the SIM.

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

Additional subscriptions are delivered wirelessly to the SIM through an OTA update. As long as your device is connected using a SIM that supports subscription containers, you can add additional subscriptions to it regardless of the device’s location.

Subscriptions can be added by signing in to the Soracom User Console, selecting a SIM that supports subscription containers, and adding a subscription. Soracom takes care of packaging subscription details (such as IMSI and authentication keys) into a subscription container and sending the additional subscription to your device.

Once your device receives the additional subscription, it is automatically added to the SIM's Soracom profile. The profile applet will then evaluate the subscription selection rules stored on the SIM and, if applicable, switch to the new subscription automatically. Refer to Subscription Priority for details.

Application Compatibility

To reduce the complexity of managing multiple subscriptions, Soracom automatically synchronizes subscription settings across all subscriptions associated with a SIM. For example, if you give your SIM a Name, change its Speed Class, or add custom Tags, these settings are also applied to any additional subscriptions on the SIM. As a result, you do not need to update 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 additional subscriptions.

Since groups are where you can enable other Soracom platform services, such as Beam, Funnel, Funk, and Harvest Data/Files, your device will also have access to the same service configurations when it uses additional subscriptions. That way, if you build your application using the primary subscription and later decide to add an additional 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 capabilities 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 an additional subscription, Soracom will automatically find the IMSI of the primary subscription and use this primary IMSI instead. Regardless of which subscription your device is currently using to connect, it will always be identified by its primary IMSI, so you do not need to re-associate your data.

Available Subscriptions

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

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

The following subscriptions are available and can be added to any planP1 SIM. Note that a planP1 primary SIM can only have one secondary subscription:

Subscription Priority

The built-in Soracom profile applet uses a PLMN mapping table loaded onto the SIM to decide which subscription to use. The table consists of swap rules: each rule says "when the modem attaches to a carrier matching this MCC/MNC, swap to subscription X." Between swaps, the SIM stays on whichever subscription it is currently using. The general priority, from most preferred to least, is:

plan-US-max > planX3 > planX2 > planX1 > planP1 > plan01s

The two behaviors that most often surprise users are:

• planX3 changes the plan01s default. When planX3 is added to a plan01s SIM, planX3 becomes the default subscription. The SIM only swaps back to plan01s when the modem attaches to a carrier in Canada or China Mainland. A SIM currently on planX3 will not automatically pick plan01s in countries where planX3 has no coverage. See Example: planX3 Added below.
• planP1 only activates in the countries defined by the PLMN rule table, even though its underlying carrier partners may have broader coverage. See Example: planP1 Added below.

plan01s SIM Subscription Priority

The table below describes which subscription is activated for common plan01s SIM combinations. For planX3 combinations, refer to the examples below the table.

^{*1 - Actual coverage in APAC depends on which subscription is activated; refer to the Supported Carriers documentation for carrier information.
*2 - 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.
*3 - Configurations that include both planX1 and planX2 subscriptions are not shown. If your SIM includes both of these subscriptions, planX2 will be prioritized.
*4 - SIMs provisioned after November 2025 will use plan-US-max when connecting to Verizon and plan01s when connecting to other carriers. SIMs provisioned before November 2025 will use plan-US-max for all carriers.}

Example: planP1 Added

When planP1 is added to a plan01s SIM, planP1 is used in the countries defined by the PLMN rule table. plan01s is used everywhere else.

Example: planX3 Added

When planX3 is added to a plan01s SIM, planX3 becomes the default subscription. The SIM only swaps back to plan01s when the modem attaches to a carrier in Canada or China Mainland. In a country where planX3 has no coverage, a SIM currently on planX3 will be unable to connect. It does not automatically pick plan01s. Review the Supported Carriers documentation before adding planX3.

The table below describes the typical case, where the SIM is on planX3 after the initial subscription is added:

Example: planX3 + Additional Subscriptions

When other subscriptions are added alongside planX3, each adds its own swap rules for specific carriers but planX3 remains the default. planP1 in particular extends coverage into several countries that would otherwise have no service. The table below describes the typical case, where the SIM is on planX3 after the initial subscription is added.

plan-US SIM Subscription Priority

When a plan-US SIM has plan-US-NA or plan-US-max subscriptions added, the subscription used depends on the carrier and country:

planP1 SIM Subscription Priority

When using a planP1 SIM with planX1 and planX3 subscriptions, the plan that is being used will differ based on country and region.

^{*1 - Actual coverage in APAC depends on which subscription is activated; Refer to the Supported Carriers documentation for carrier information.
*2 - Connectivity in Japan is provided by SoftBank only for planP1; by SoftBank and au/KDDI (plus NTT Docomo by request) for planX1; and by SoftBank and NTT Docomo for planX3.
*3 - planP1 does not provide coverage outside of the APAC region, Japan, or the United States. When planX3 is added, planX3 will be prioritized wherever coverage is available. In some cases, planX3 may have access to fewer networks compared to planP1, which may result in reduced carrier coverage in APAC.}

Requirements

To use the Subscription Container feature, your device must meet 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 primary subscription as well as the additional subscription

• 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 SIM, note the following limitations:

• Once an additional subscription is added to a SIM, it cannot be removed. To terminate a subscription, you must terminate the SIM.
• When one or more additional subscriptions 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 additional subscription as follows:
  • For planX1 and planX2, the additional subscription 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 additional subscription 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 additional subscriptions are added to a plan-US SIM, an additional subscription fee will be added to the monthly basic fee.
• When one or more additional subscriptions are added to a planP1 SIM, the SIM will no longer incur the planP1 basic fees. However, the SIM will continue to incur the monthly basic fee for each additional subscription as follows:
  • For planX1, the additional subscription monthly basic fee will still be charged even if the SIM is set to Standby or Suspended status.
  • For planX3, the additional subscription 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.
• 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 countries or regions where the device is connected using a subscription that supports MO-SMS.
• 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 its additional subscriptions.
• When a planX3 subscription is added to a plan01s or planP1 SIM, the planX3 subscription will be prioritized wherever coverage is available. In some cases, planX3 may have access to fewer networks compared to plan01s or planP1, which may result in reduced carrier coverage.
• Subscription priorities cannot be changed from their default configuration.

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. Sign in 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.

   

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

   

5. A dialog box will appear asking you to confirm your choice. Read and acknowledge the warnings associated with adding an additional subscription, 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 additional subscriptions have been added:

For each SIM, the IMSI column will contain 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 delivery 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, you can retrigger the OTA update from the OTA Updates tab on the SIM Details page.

Managing OTA Updates

From the OTA Updates tab on the SIM Details page, you can check the status of OTA updates and retrigger (re-execute) failed updates.

Checking OTA Update Status

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

2. Click the target SIM to open the SIM Details page.

3. Click the OTA Updates tab.

   

4. The OTA updates list will be displayed.

   

   The table displays the following information:

   Column	Description
   Update reference	An identification tag for the update. Click to view details.
   Status	The overall progress status of the update, displayed with color coding.
   Started time	The date and time the update started.
   Last updated	The date and time of the last update.

Viewing OTA Update Details

1. In the OTA updates list, click the Update reference for the update you want to view.

2. Review each item.

   

   No.	Item	Description
   ①	ICCID	The ICCID of the SIM.
   ②	Update reference	An identification tag for the update.
   ③	Status	The overall progress status of the update.
   ④	Last record status	The status of the latest OTA record.
   ⑤	Updates sent	The number of scripts sent / total number of scripts.

Retriggering a Failed OTA Update

You can retrigger updates with a FAILED status.

1. In the OTA updates list, click the Update reference for an update with a FAILED status. This will display the update details modal with the Retry OTA update section at the bottom.

   

2. Click Retry OTA update.

If the IoT SIM is offline, a warning message will be displayed and the OTA will be automatically retriggered when the device next comes online.

![Retrigger result screen (IoT SIM offline)](./ota-retrigger-offline.png)

If the IoT SIM is online, the OTA update is re-executed immediately.

3. On the result screen, click Back to OTA update details to check the latest status, or click Close to close the modal and return to the updates list.

Understanding Statuses

Update Status

The update status represents the overall progress of the update.

Last Record Status

The last record status represents the status of the latest OTA record. This value is independent of the update status.

Even when the update status is COMPLETED, the last record status may show a different value such as FINISHED or DELIVERED. Check the update status for the final result of the update.

Programmatic Usage

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

[block=api]

Soracom API

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

Then, use the addSubscription API to add an additional subscription to an IoT SIM or Arc Virtual SIM:

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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

[/ui-tab] [/ui-tabs] [/block]

[block=cli]

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 an additional subscription to an IoT SIM or Arc Virtual SIM:

[ui-tabs theme=code] [ui-tab title=Global]

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

[/ui-tab] [ui-tab title=Japan]

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

[/ui-tab] [/ui-tabs]

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

[/block]