Subscriber Status

Each Air SIM in your account will have a Status label that indicates its subscription state and session status. Each status corresponds to a different network connectivity and billing behavior.

https://console.soracom.io

Subscriber Status


Statuses

Status Description
Ready Registration complete, ready for use
Active OFFLINE Subscription enabled but device has not established a data session*1
Active ONLINE Subscription enabled and device has established a data session
Inactive Subscription enabled but data sessions are temporarily blocked
Standby Subscription disabled
Suspended Subscription disabled
Terminated Subscription cancelled

*1 - Even if a device is powered on and registered to a network, it may not have established a data session, such as if the Access Point Name (APN) is not properly configured or if data roaming is disabled. Although the device may still be able to access SMS services, it will appear as offline.

Ready

When you register an Air SIM to your account, its initial subscription status is set to Ready. This status indicates that the registration process was completed successfully and that the SIM is now ready for use.

As soon as a device initiates a cellular connection request, the subscription status will automatically change to Active. No fees are incurred when the subscription is activated for the first time.

Ready Status Fees

  • plan01s, plan01s - LDV, plan-NA1, and plan-KM1 subscriptions do not incur fees while Ready. However, an annual subscription renewal fee applies if the subscription remains in Ready status for more than 1 year.
  • plan-US subscriptions do not incur fees during the first 6 months of Ready status. However, a monthly subscription renewal fee applies if the subscription remains in Ready status for more than 6 months.
  • plan-D and plan-K subscriptions incur a reduced daily basic fee while Ready.
  • plan-DU subscriptions do not incur fees for the first 2 months while the subscription is Ready. After that, a reduced monthly fee applies as long as the subscription remains Ready.

Active

A subscription with an Active status indicates that data sessions are allowed. While Active, the status will also indicate whether the SIM is currently Offline or Online.

The Online or Offline status only refers to the subscription's current data session status, not to the status of the device using the SIM.

  • When a device successfully attaches to a network and creates a data session, the subscription status will appear as Online.
  • In some cases, a device may be configured to create a data session manually, or it may have encountered an error when creating a data session. As the subscription does not have an active data session, it will appear as Offline even if the device is powered on.
  • Similarly, if a subscription currently appears Online and the device is abruptly disconnected from the network (such as removing the device's battery or power input), the device will not have a chance to notify the network of ending the data session. As a result, the subscription may continue to appear Online for up to one hour after the device has been powered off.

Active Status Fees

  • plan01s, plan-D, and plan-K subscriptions incur a daily basic fee while Active, as well as any fees for data used.
  • plan01s - LDV and plan-KM1 subscriptions incur a monthly basic fee while Active, as well as any fees for data used.
  • plan-US, plan-NA1, and plan-DU subscriptions incur a monthly basic fee while Active, which includes a data usage allowance in the monthly fee.

Inactive

When a subscription is set to Inactive, data sessions are blocked. This status can be used to temporarily prevent a device from consuming any data when network connectivity is not required. As a result, no data usage fees are incurred in this status.

Although data sessions are blocked, your device may continually attempt to reconnect, which could result in excessive power consumption. An appropriate reconnection process is recommended, such as exponentially increasing the duration between reconnection attempts, or implementing a reconnection timeout after a set number of attempts.

Inactive Status Fees

  • plan01s, plan-D, and plan-K subscriptions continue to incur the same daily basic fee while Inactive.
  • plan01s - LDV and plan-KM1 subscriptions continue to incur the same monthly basic fee while Inactive.
  • plan-US, plan-NA1, and plan-DU subscriptions continue to incur the same monthly basic fee while Inactive.

Standby

When a subscription is set to Standby, it will behave similarly to the original Ready status, where no basic fees or data usage fees are incurred. As soon as a device initiates a cellular connection request, the subscription status will automatically change to Active again.

This status can be used to control subscription costs when your SIMs will not be used for an undetermined amount of time, and where you want the subscription to automatically reactivate when the device is turned on again.

Unlike the Ready status, a reactivation fee applies when the subscription status changes from Standby to Active or Inactive.

Before changing a subscription status to Standby, ensure that your device is fully powered off in order to prevent accidental reactivation.

Standby Status Fees

  • plan01s, plan01s - LDV, and plan-KM1 subscriptions do not incur daily or monthly basic fees while in Standby. There is no fee to set the subscription status to Standby, however a reactivation fee is incurred when the subscription is reactivated. In addition, an annual subscription renewal fee applies if the subscription remains in Standby status for more than 1 year.
  • plan-US subscriptions incur the full monthly basic fee for the month that the subscription status is set to Standby. There is no fee to set the status to Standby, and no monthly basic fees are incurred starting from the following month for up to 6 months, after which a monthly subscription renewal fee applies. Similarly, no reactivation fee is incurred when the subscription is reactivated, however the full monthly basic fee applies for the month that the subscription is reactivated.
  • plan-NA1, plan-D, plan-DU, and plan-K subscriptions do not support Standby status.

Suspended

When a subscription is set to Suspended, data sessions are blocked, and the SIM does not incur daily or monthly basic fees. This status can be used to prevent a device from consuming any data and to control subscription costs when network connectivity is not required for an extended amount of time.

Although data sessions are blocked, your device may continually attempt to reconnect, which could result in excessive power consumption. An appropriate reconnection process is recommended, such as exponentially increasing the duration between reconnection attempts, or implementing a reconnection timeout after a set number of attempts.

Unlike the Standby status, all data sessions will be blocked, and the subscription must be manually reactivated before a device using the SIM can connect to a network again.

Important! If a device attempts to connect to a network while a subscription is Suspended, Soracom will send a signal to the device informing that the connection is permanently rejected, which will cause the device to stop attempting to reconnect. After manually reactivating a Suspended subscription, the device must also be manually rebooted or power-cycled in order to resume network connections. Before changing a subscription to Suspended status, ensure that you will be able to access the device in order to reboot it when reactivating the subscription.

Similar to the Standby status, a reactivation fee applies when the subscription status changes from Suspended to Active or Inactive.

Suspended Status Fees

  • plan01s, plan01s - LDV, and plan-KM1 subscriptions do not incur daily or monthly basic fees while Suspended. There is no fee to set the subscription status to Suspended, however a reactivation fee is incurred when the subscription is reactivated. In addition, an annual subscription renewal fee applies if the subscription remains in Suspended status for more than 1 year.
  • plan-US subscriptions incur the full monthly basic fee for the month that the subscription status is set to Suspended. There is no fee to set the status to Suspended, and no monthly basic fees are incurred starting from the following month for up to 6 months, after which a monthly subscription renewal fee applies. Similarly, no reactivation fee is incurred when the subscription is reactivated, however the full monthly basic fee applies for the month that the subscription is reactivated.
  • plan-NA1 subscriptions do not support Suspended status.
  • plan-D and plan-K subscriptions incur a reduced daily basic fee while Suspended. A suspension fee is incurred when the subscription status is changed from Active or Inactive to Suspended.
  • plan-DU subscriptions continue to incur the same monthly basic fee while Suspended.

Terminated

If you no longer need your Air SIM, you can terminate its subscription by changing its status to Terminated. There are no fees to terminate a subscription, and once terminated, all service will stop and no further basic fees or data usage fees are incurred.

Changing a subscription status to Terminated is a permanent and irreversible action. Terminated SIMs will no longer be able to establish cellular connections. If you need to re-enable a SIM that has been terminated, you must purchase a new SIM, register it to your account, and replace the terminated SIM card in your device with the new SIM.

Terminated SIMs will remain visible in your account for a certain duration, and will eventually be automatically removed from your account.

Terminated Status Fees

  • There are no fees for terminating a subscription.

Viewing Status Update History

You can view the history of changes to a SIM's status.

The following actions are recorded as part of a SIM's status history

To view the SIM update history:

  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 view, then click the Details button.
    https://console.soracom.io

    Subscriber details

  3. Select Update History to view all changes that have been recorded for your SIM

Update History

Please note that SIM status update history does not contain information about the following:

  • The source of the SIM status change. For example, whether a SAM User or Event Handler made the change.
  • Session history or data usage history. Instead, use the Session Details and Historical Charts tabs, respectively.
  • Details of what group settings were changed

Changing a Subscription Status

For security reasons Soracom support agents are unable to make changes to SIM statuses on the behalf of customers.

To change the status of a subscription:

  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 one of the following:

    https://console.soracom.io

    Change subscription status

    • To set its status to Active, select Activate.
    • To set its status to Inactive, select Deactivate.
    • To set its status to Standby, select Set to Standby.
    • To set its status to Suspended, select Suspend.
    • To set its status to Terminated, select Terminate.

Changing a subscription status to Terminated is a permanent and irreversible action. For more information, please refer to the Termination documentation.


Viewing Detailed Session Status

You can also view additional details of an Air SIM's current or past sessions.

  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 view, then click the Details button.

    https://console.soracom.io

    View subscriber details

  3. From the SIM Details dialog, click the Session details tab. Session history

Within the Session details tab, you will see a Session Logs table with the following information:

Session logs are retained for a maximum of 32 days and will no longer appear afterwards.


Deleting an Online Session

In some cases, it's useful to delete an existing data session in order to force an Air SIM device to reconnect, such as to receive new custom DNS settings or update Group settings. You can delete an Air SIM's existing session directly from the User Console:

Deleting a session will only end the existing data session. Your device must be configured to automatically create a new data session in order to reconnect to a cellular network. If your device is not configured to reconnect, you may need to access the device directly to reboot the device or manually initiate a new data session.

  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 Delete session.

    https://console.soracom.io

    Delete session

  4. A warning will appear asking you to confirm the action. Click Delete to confirm.

Programmatic Usage

You can programmatically check the status of an Air SIM subscription as well as its session status using the Soracom API, CLI, or Air SIM Metadata Service.

When using the API or CLI, you will need the IMSI number of the subscription.

Soracom API

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

Then, use the getSubscriber API to get the subscription and session status of an Air SIM:

curl -X GET \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>

The API will return a JSON response similar to the following:

{
  "imsi": "295050012345678",
  "msisdn": "423012345678",
  "ipAddress": "10.123.45.67",
  "operatorId": "OP0012345678",
  "apn": "soracom.io",
  "type": "s1.standard",
  "groupId": "abcdef00-0000-0000-0000-000012345678",
  "status": "active",
  "tags": {
    "name": "my-sim"
  },
  "sessionStatus": {
    "imei": "860000012345678",
    "cell": {
      "radioType": "lte",
      "mcc": 310,
      "mnc": 410,
      "lac": 42973,
      "sac": 14702,
      "rac": 255
    },
    "ueIpAddress": "10.123.45.67",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  },
  "speedClass": "s1.standard",
  "moduleType": "trio",
  "plan": 1,
  "iccid": "8942310000012345678",
  "subscription": "plan01s"
}

The status property will indicate the current subscription status of the Air SIM, while the sessionStatus.online property will indicate whether or not the subscriber is currently connected.

To change the status of a subscriber, use one of the following APIs:

You can also use one of the following APIs to perform the same actions on a per-SIM basis:

The /sims/ level APIs will provide the same functionality as the /subscribers/ level APIs, with forward compatibility for SIMs which contain more than one Subscription Container.

To delete an ongoing session or list session history, use the following APIs:

Similarly, you can use the following APIs to perform the same actions on a per-SIM basis:

When using the listSessionEvents and listSimSessionEvents APIs, only the session logs from the previous 32 days will be returned.

You can use the following API to retrieve the SIM Status History

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 get the subscription and session status of an Air SIM:

soracom subscribers get --imsi <IMSI> --coverage-type g

The CLI will return a response similar to the API example above.

To change the status of a subscriber, use one of the following CLI commands:

  • soracom subscribers activate
  • soracom subscribers deactivate
  • soracom subscribers set-to-standby
  • soracom subscribers suspend
  • soracom subscribers terminate

You can also use one of the following CLI commands to perform the same actions on a per-SIM basis:

  • soracom sims activate
  • soracom sims deactivate
  • soracom sims set-to-standby
  • soracom sims suspend
  • soracom sims terminate

To delete an ongoing session or list session history, use:

  • soracom subscribers delete-session
  • soracom subscribers session-events

Similarly, you can use the following CLI commands to perform the same actions on a per-SIM basis:

  • soracom sims delete-session
  • soracom sims session-events

When using the sims commands, the same limitations apply as noted in the API example above.