# Expiration

Temporarily disable SIMs to prevent unwanted usage or when connectivity is not needed.

In some applications, you may want to end your device's data session or suspend or terminate your subscription at a pre-determined date and time. The Expiration function allows you to set your IoT SIM to perform a one-time action.

## Expiry Actions

The following actions are available when setting an Expiry Action for an Air subscriber:

- **Do nothing** - Allow any existing connections to continue, but block all future connections.
- **Delete session** - Forcibly end any existing connections and block all future connections.
- **Deactivate** - Forcibly end any existing connections and change the subscription status to **Inactive**.
- **Suspend** - Forcibly end any existing connections and change the subscription status to **Suspended**.
- **Terminate** - Forcibly end any existing connections and terminate the subscription.

When setting the **Do nothing** or **Delete session** actions, the subscription status will not be changed. Any daily basic fees associated with the existing status will continue. The Expiry Action date and time must be cleared or extended in order for the subscriber to establish new connections.

When setting the **Deactivate** or **Suspend** actions, the subscription status will be changed to **Inactive** or **Suspended**, respectively, at the specified date / time. Any daily basic fees for each status will apply according to the subscription plan. The subscription status must be changed back to **Active** and its Expiry Action date / time must be cleared or extended in order for the subscriber to establish new connections.

> [!NOTE]
>
> When setting the **Terminate** action, the subscription will be permanently terminated at the specified date / time. The subscription cannot be re-activated and no further connections will be possible.

## Configuration

### Set or Update an Expiry Action

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **SIM Management** screen.

2. From the list of subscribers, click the **☑** for the SIM you want to modify.

3. Click the **Actions ▾** menu, then select **Change expiration**.

   ![Change expiry](https://docs.soracom.io/_astro/change-expiry.wSY2wRB2_Z1g2mY5.webp)

4. Select an **Expiry Action** and set the expiration **date and time**.

   ![Expiry Action](https://docs.soracom.io/_astro/expiry-action.Cmqq-HlL_1kq9oN.webp)

5. Click **Change Expiration Date**

### Remove an Expiry Action

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **SIM Management** screen.

2. From the list of subscribers, click the **☑** for the SIM you want to modify.

3. Click the **Actions ▾** menu, then select **Change expiration**.

4. Select **No expiry action**, then click **Change Expiration Date**.

## Programmatic Usage

You can also use the Soracom API, Soracom CLI, and Metadata Service to enable or disable expiration.

### Soracom API

To access the Soracom API, first use the [**auth**](https://docs.soracom.io/en/api#!/Auth/auth) API to obtain an API Key and Token. Refer to the [**API Usage Guide**](https://docs.soracom.io/en/developers/soracom-api) for instructions on how to use the API Key and Token in API requests.

Then, use the [setSimExpiryTime](https://docs.soracom.io/en/api#!/Sim/setSimExpiryTime) API to enable expiration on an IoT SIM:

**Global**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "expiryAction": "deleteSession",
        "expiryTime": 1704067200000
      }' \
  https://g.api.soracom.io/v1/sims/<SIM-ID>/set_expiry_time
```

**Japan**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "expiryAction": "deleteSession",
        "expiryTime": 1704067200000
      }' \
  https://jp.api.soracom.io/v1/sims/<SIM-ID>/set_expiry_time
```

To remove expiration from an IoT SIM, use the [unsetSimExpiryTime](https://docs.soracom.io/en/api#!/Sim/unsetSimExpiryTime) API:

**Global**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://g.api.soracom.io/v1/sims/<SIM-ID>/unset_expiry_time
```

**Japan**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://jp.api.soracom.io/v1/sims/<SIM-ID>/unset_expiry_time
```

### 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 enable expiration on an IoT SIM:

**Global**

```bash
soracom sims set-expiry-time --sim-id <SIM-ID> --expiry-action "deleteSession" --expiry-time 1704067200000 --coverage-type g
```

**Japan**

```bash
soracom sims set-expiry-time --sim-id <SIM-ID> --expiry-action "deleteSession" --expiry-time 1704067200000 --coverage-type jp
```

To remove expiration from an IoT SIM, use following command:

**Global**

```bash
soracom sims unset-expiry-time --sim-id <SIM-ID> --coverage-type g
```

**Japan**

```bash
soracom sims unset-expiry-time --sim-id <SIM-ID> --coverage-type jp
```

### Metadata Service

The Metadata Service allows an Air SIM device to access and configure its own settings without the need for authentication. For more information, refer to the [**Metadata Service**](https://docs.soracom.io/en/services/air/metadata-service) documentation.

Because the Metadata Service allows an IoT SIM to access its own subscriber settings, this can be used as part of an initialization script so that a device sets its own expiration when it connects to a network for the first time.

To enable expiration on an IoT SIM, the Metadata Service **Readonly** option must be disabled. Then, from the IoT SIM device, use the [setExpiryTime](https://docs.soracom.io/en/api#!/Subscriber/setExpiryTime) API:

```bash
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
        "expiryAction": "deleteSession",
        "expiryTime": 1704067200000
      }' \
  http://metadata.soracom.io/v1/subscriber/set_expiry_time
```

Since the subscriber will be online, you can also omit the payload in order to lock the subscriber to its current IMEI.

To remove IMEI lock from the IoT SIM, use the [unsetExpiryTime](https://docs.soracom.io/en/api#!/Subscriber/unsetExpiryTime) API:

```bash
curl -X POST http://metadata.soracom.io/v1/subscriber/unset_expiry_time
```