What Is a Subscription Container?
Subscription containers are a feature of plan01s and plan-US IoT SIMs that allow you to add additional subscription plans to a SIM. This enables the SIM to access lower data rates in specific regions or expand its coverage to more countries and networks.
What Are the Device Requirements?
To use Subscription Containers, a device must support:
- SIM Application Toolkit (STK) commands
- Sending and receiving SMS messages (SMS MO/MT), which is required for the Over-the-Air (OTA) update process
Note: The NB-IoT network does not support SMS. As a result, SIMs used in NB-IoT devices cannot receive Subscription Container updates.
How Is a Subscription Container Added?
You can add a subscription to a SIM using the Soracom User Console or by calling the addSubscription API endpoint.
This action triggers an Over-the-Air (OTA) update to the SIM. If the device is online, the OTA download is immediately initiated. If the device is offline, the download will begin the next time the device creates a data session.
What Happens if the OTA Update Fails?
The delivery of a subscription occurs via an OTA update that uses several SMS messages. If a device's cellular connection is unstable or disconnects while the update is in progress, the process can be interrupted. This may cause the subscription container's status to remain stuck in "shipped" or "delivered".
If this happens, you can manually trigger a retry of the OTA update by performing one of the following actions:
- Delete the device's session from the User Console.
- Reboot the device in a location with good cellular reception.
Soracom will automatically retry the update process. If a SIM's status remains stuck for an extended period, the automatic retries may have been exhausted. In this case, please contact Soracom Support for assistance.
What Subscription Container Delivery Statuses Can I See?
You can monitor the progress of the OTA update in the User Console or via the API. The delivery status will be one of the following:
- shipped: Soracom has prepared the subscription and is either waiting for the device to come online or has sent the OTA update and is waiting for the SIM to acknowledge receipt.
- delivered: The SIM has confirmed it received the OTA update. Soracom is now sending the necessary subscription information (such as IMSI and authentication data) to the SIM for installation.
- ready: The subscription container was successfully installed on the SIM, and your device can now use it.
Can I Delete Subscriptions I Have Added?
No, adding a subscription to a SIM is an irreversible action. Once added, a subscription cannot be removed.
How Does the SIM Select Which Subscription to Use?
When a new subscription is added, the SIM's subscription container engine will automatically select the most suitable plan for the country it is in. This selection happens when the device notifies the SIM of the available network information.
The preferred subscription automatically selected by the SIM depends on the plans you have downloaded. For more details, please refer to our Subscription Priority documentation.