Soracom Air for Cellular

Transferring Soracom IoT SIMs

Once an IoT SIM has been registered to a Soracom operator account, all aspects of the SIM, such as configuration and billing, will be associated with that account. In some cases, you may want to manage a SIM using a different Soracom operator account, such as maintaining a separate account for a different project or department, or giving control of a SIM to an end-user. Although an IoT SIM cannot be registered to more than one Soracom operator account at a time, its registration can be transferred from one account to another. Depending on the subscriber status of your SIM, please see the table below for the appropriate next steps.

Subscriber Status Next Steps
Ready Self-service transfer using the User Console or API. See Transferring Ready status SIMs.
Active ONLINE, Active OFFLINE, Inactive, Standby or Suspended Support-assisted transfer upon request. See Transferring SIMs in Other Statuses.
Terminated Terminated SIMs cannot be transferred. Please purchase a new SIM through your User Console account or that of the destination operator account.

Once a SIM has switched from Ready to another status, it cannot be switched back. If you are planning to transfer a Ready status SIM, you must ensure that the SIM will not be used to connect to a network prior to completing the transfer. If the SIM is used to connect to a network before or during the transfer process, such as to verify that a device is working properly, its status will automatically change to Active, and you will need to use the steps outlined in Transferring SIMs in Other Statuses to transfer it.

Transferring Ready Status SIMs

You can transfer Ready status IoT SIMs to another operator account directly from the User Console or programmatically using the Soracom API. The basic transfer process is illustrated below.

Overview

Limitations

When transferring Ready SIMs, the following SIM settings are not transferred from the source operator account:

If these settings are required for a devices to function after their SIMs have been transferred, please ensure that the owner of the destination operator account is made aware that additional configuration is required after the transfer.

Initiating a SIM Transfer

Any fees associated with the SIMs being transferred will be billed to the source operator account until the transfer has been completed. Once the destination operator account has accepted the transfer, any new fees associated with the SIMs will be billed to the destination operator account.

To transfer a Ready status SIM, you will need the following:

To obtain the destination operator's primary email address or Operator ID, please contact the owner of the destination operator account. They will be able to obtain theses details by logging into the User Console and selecting their account drop-down in the top right.

Before proceeding, please ensure that the destination operator will be available to accept the transfer, as the link sent via email expires after 1 hour.

To begin transferring Ready SIMs:

  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 transfer.

  3. Click the Actions menu, then select Transfer to another operator.

  1. Enter the destination operator Email and ID, then click Transfer.

    • Destination Operator Email - The primary email address of the destination operator.
    • Destination Operator ID (OP + 10 digits) - The operator ID of the destination operator.

Once you have initiated the SIM transfer, the status of each SIM will change to Transferring, and an email will be sent to the destination operator through which the transfer can be accepted and completed.

During this transfer process, please ensure that the SIMs will not be used to connect to a network, and that the SIM status is not changed from Transferring. If the SIM status changes, the transfer process will be aborted, and you will no longer be able to use this method to transfer the SIMs to another account.

To complete the transfer, the owner of the destination operator account will need to accept the transfer using the steps in the next section.

Accepting a SIM Transfer

A registered payment method is required on the destination operator account to accept SIM transfers. Please refer to the Register a Payment Method for more information.

To accept a SIM transfer request:

  1. Login to the User Console.

  2. If necessary, change the Coverage Type (Global Coverage or Japan Coverage) to match that of the SIMs being transferred. Refer to Coverage Types for more information.

  3. Using the same browser, open the SIM transfer request email that was sent to the primary email address of the destination operator account and click the URL included in the email.

    Clicking the link in the SIM transfer request email will immediately accept the transfer request upon opening the page. If you are not signed in, you may be prompted to do so first, upon which the transfer request will be completed.

    If you are not expecting a SIM transfer or do not wish to accept a transfer request, you may safely ignore the SIM transfer request email.

Once you have accepted the SIM transfer request, the SIMs will appear in your account, and you can begin using the SIMs by installing them in your devices and setting up the Soracom APN information as needed.

If the transferred SIMs require a specific configuration to function with existing devices, please reach out to the owner of the source operator account to determine the appropriate configuration.

Cancelling a SIM Transfer

If you need to cancel the transfer of a SIM:

  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 cancel.
  3. Click the Actions menu, then select Cancel Transfer.

Cancelling a SIM transfer will cancel the transfer of all SIMs included in the original request. It is not possible to cancel individual SIMs within a multi-SIM transfer request. If you need to remove individual SIMs from a SIM transfer, please cancel the original request, and restart the transfer process.

SIM transfers cannot be canceled if the destination operator has already accepted the transfer.

Transferring Other Status SIMs

To transfer SIMs that are in the Active, Inactive, Standby, or Suspended status, please submit a SIM transfer request to Soracom by following the instructions below. Soracom will handle the process of transferring SIMs on your behalf.

Conditions and Limitations

When transferring Active, Inactive, Standby, or Suspended status SIMs, the following conditions and limitations apply:

  • A valid payment method for the appropriate region must be associated with the destination operator account. SIMs cannot be transferred to an account that does not have a valid payment method configured. Please note that payment methods are registered seperately for Japanese and Global coverages. Please refer to the Payment Settings for more information.

  • Any fees associated with the SIMs being transferred will be billed to the source operator account until the transfer has been completed. Once the transfer operation has been completed, any new fees associated with the SIMs will be billed to the destination operator account.

  • Once a SIM transfer request has been confirmed and processed, a SIM transfer fee will be charged to the source operator account. Refer to Pricing & Fee Schedule for more information.

If your device is not configured to create a new data session automatically, you may need to restart or reboot your device after the transfer has occured.

Initiating a SIM Transfer Request

To submit a SIM transfer request, you will need the following:

To submit a SIM transfer request:

  1. Login to the Soracom support site using the source operator account.

  2. Access the following link to open the SIM transfer request form, then fill in the required fields and submit the request:

Once you have submitted your request, Soracom will verify that the source operator has submitted the ticket, a valid payment method is in place on the destination operator account, and that the appropriate terms and conditions for Air usage have been accepted. If no payment method is present or the appropriate terms and conditions have not been accepted, our team will inform you of the issue. The transfer cannot preoceed until it has been rectified.

Next, we will send a confirmation email to the primary email address of the destination operator account. If we do not receive confirmation from the recipient, the SIM transfer process cannot proceed.

Once confirmation has been received, we will proceed with the SIM transfer request. You will receive confirmation on the first of the coming month or the first of the following month once the transfer has been completed, depending on the date that the destination operator's confirmation was recieved.

Programmatic Usage

You can also use the Soracom API and Soracom CLI to transfer Ready status SIMs.

SIMs that are in the Active, Inactive, Standby, or Suspended statuses cannot be transferred using the Soracom API or Soracom CLI. Please refer to Transferring SIMs in Other Statuses for further steps on transferring these SIMs.

Soracom API

To access the Soracom API, first use the auth API with the source operator account 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.

Next, use the issueSubscriberTransferToken API to initiate a SIM transfer:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "transferDestinationOperatorEmail": "<DESTINATION-OPERATOR-EMAIL>",
>        "transferDestinationOperatorId": "<DESTINATION-OPERATOR-ID>",
>        "transferImsi": [
>          "<IMSI-TO-TRANSFER-1>",
>          "<IMSI-TO-TRANSFER-2>",
>          "<IMSI-TO-TRANSFER-3>"
>        ]
>      }' \
>  https://g.api.soracom.io/v1/subscribers/transfer_token/issue

The status of the SIMs will change to Transferring, and the API will return a JSON response containing a token needed to accept the transfer:

{
  "token": "abcdef00-1111-2222-3333-444444444444-abcdef00-5555-6666-7777-888888888888"
}

During the transfer process, make sure that the SIMs will not be used to connect to a network, and that the SIM status is not changed from Transferring. If the SIM status changes, the transfer process will be aborted, and you will no longer be able to use this method to transfer the SIMs to another account.

If you want to cancel the SIM transfer, use the deleteSubscriberTransferToken API with the transfer token:

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

Cancelling a SIM transfer will cancel the transfer of all SIMs included in the original request. It is not possible to selectively remove individual SIMs. If you need to remove individual SIMs from a SIM transfer, please cancel the original token, and generate a new token with a new set of SIMs to transfer.

Next, provide the token to the owner of the transfer destination operator account.

Finally, use the auth API with the destination operator account to obtain a new API Key and Token, and then use the verifySubscriberTransferToken API to accept the SIM transfer:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "token": "<TRANSFER-TOKEN>"
>      }' \
>  https://g.api.soracom.io/v1/subscribers/transfer_token/verify

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Note that you will need to run the CLI using the source operator account credentials to initiate the SIM transfer, and then using the destination operator account credentials to accept the transfer. If you have credentials for both accounts, you can use the --profile <PROFILE-NAME> flag to switch between accounts with the CLI.

Next, use the following command with the source operator account to initiate a SIM transfer:

soracom subscribers issue-transfer-token \
>  --profile "<SOURCE-OPERATOR-PROFILE-NAME>" \
>  --transfer-destination-operator-email "<DESTINATION-OPERATOR-EMAIL>" \
>  --transfer-destination-operator-id "<DESTINATION-OPERATOR-ID>" \
>  --body '{
>    "transferImsi": [
>      "<IMSI-TO-TRANSTER-1>",
>      "<IMSI-TO-TRANSTER-2>",
>      "<IMSI-TO-TRANSTER-3>"
>    ]
>  }' \
>  --coverage-type g

Similar to the API above, the status of the SIMs will change to Transferring, and the CLI will return a JSON response containing the token needed to accept the transfer:

{
  "token": "abcdef00-1111-2222-3333-444444444444-abcdef00-5555-6666-7777-888888888888"
}

During the transfer process, make sure that the SIMs will not be used to connect to a network, and that the SIM status is not changed from Transferring. If the SIM status changes, the transfer process will be aborted, and you will no longer be able to use this method to transfer the SIMs to another account.

If you want to cancel the SIM transfer, run the following command with the transfer token:

$ soracom subscribers delete-transfer-token --profile "<SOURCE-OPERATOR-PROFILE-NAME>" --token "<TRANSFER-TOKEN>" --coverage-type g

Cancelling a SIM transfer will cancel the transfer of all SIMs included in the original request. It is not possible to selectively remove individual SIMs. If you need to remove individual SIMs from a SIM transfer, please cancel the original token, and generate a new token with a new set of SIMs to transfer.

Next, provide the token to the owner of the transfer destination operator account.

Finally, run the following command with the destination operator account to accept the SIM transfer:

$ soracom subscribers verify-transfer-token --profile "<DESTINATION-OPERATOR-PROFILE-NAME>" --token "<TRANSFER-TOKEN>" --coverage-type g