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 , , and 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.

Depending on your device's cellular network compatibility, adding an additional subscription may cause connectivity problems when connecting to a cellular network. Refer to the Requirements and Limitations sections below.

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.

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 SIM:

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

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

Subscription Priority

must be manually selected by using AT commands on your module. Once selected, it will take precedence over other subscriptions on the SIM card.

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:

The two behaviors that most often surprise users are:

• ** changes the default**. When is added to a SIM, becomes the default subscription. The SIM only swaps back to when the modem attaches to a carrier in Canada or China Mainland. A SIM currently on will not automatically pick in countries where has no coverage. See Example: planX3 Added below.
• ** 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 SIM combinations. For 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 ; by SoftBank only for ; by SoftBank and au/KDDI (plus NTT Docomo by request) for ; by au/KDDI only for ; and by SoftBank and NTT Docomo for .
*3 - Configurations that include both and subscriptions are not shown. If your SIM includes both of these subscriptions, will be prioritized.
*4 - SIMs provisioned after November 2025 will use when connecting to Verizon and when connecting to other carriers. SIMs provisioned before November 2025 will use for all carriers.}

Example: planP1 Added

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

Example: planX3 Added

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

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

Example: planX3 + Additional Subscriptions

When other subscriptions are added alongside , each adds its own swap rules for specific carriers but remains the default. 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 after the initial subscription is added.

plan-US SIM Subscription Priority

When a SIM has or subscriptions added, the subscription used depends on the carrier and country:

planP1 SIM Subscription Priority

When using a SIM with and 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 ; by SoftBank and au/KDDI (plus NTT Docomo by request) for ; and by SoftBank and NTT Docomo for .
*3 - does not provide coverage outside of the APAC region, Japan, or the United States. When is added, will be prioritized wherever coverage is available. In some cases, may have access to fewer networks compared to , 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) !!! As the NB-IoT network does not support SMS, SIM cards in NB-IoT devices will be unable to receive additional subscriptions.

• 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

  !!!! If your device does not support the network type or frequency bands of a particular country or network, it will not automatically revert to the primary 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 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 , your device will no longer be able to connect to a network. !!!! !!!! If you have any concerns about compatibility, feel free to contact Soracom Support.

• Your SIM card is in Active status and in a data session ([span class="text-green"][fa=check-circle extras=lg/] Active[/span] ).

  • It is possible to order an additional subscription for a SIM when it is in Active status but not in a data session ([span class="text-grey"][fa=circle-o extras=lg/] Active[/span] ), but the OTA process will not occur until the device creates a new data session ().

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 SIM, the SIM will no longer incur the daily basic fees. However, the SIM will continue to incur the monthly basic fee for each additional subscription as follows:
  • For and , the additional subscription monthly basic fee will still be charged even if the SIM is set to Standby or Suspended status.
  • For , , and 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 SIM, an additional subscription fee will be added to the monthly basic fee.
• When one or more additional subscriptions are added to a SIM, the SIM will no longer incur the basic fees. However, the SIM will continue to incur the monthly basic fee for each additional subscription as follows:
  • For , the additional subscription monthly basic fee will still be charged even if the SIM is set to Standby or Suspended status.
  • For , 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, 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, 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 subscription.
• Similarly, , , and 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 subscription. There is no support for USSD on or any of its additional subscriptions.
• When a subscription is added to a or SIM, the subscription will be prioritized wherever coverage is available. In some cases, may have access to fewer networks compared to or , which may result in reduced carrier coverage.
• Subscription priorities cannot be changed from their default configuration.

Adding a Subscription

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

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.

In most cases, delivery and activation of an additional subscription will be completed in less than 10 minutes from the time the device comes online.

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 , , , , , or 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.

This feature is only available for Global coverage IoT SIMs. The OTA Updates tab is not displayed for Japan coverage SIMs.

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.

Retriggering applies only to the selected IoT SIM. Batch retriggering for multiple SIMs is not supported.

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.

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:

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 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:

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

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