Replace a SIM

Preview

To replace the SIM associated with an existing subscription, submit an order request within the Order API. This allows clients to seamlessly change their SIMs from SIM to eSIM.

note

This documentation covers the preview version of the Orders API. Please note that this preview API is provided for early access to new features and for collecting feedback. Therefore, it is not intended for use in a production environment.

How it works

Submit a Change SIM Profile Request

Clients initiate the process by sending a POST request to the https://api.1global.com/enterprise/orders endpoint. This request includes all necessary parameters to define the current subscription and the new SIM profile.

To issue the request:

curl -X POST \
  https://api.1global.com/enterprise/orders \
   -H 'Authorization: Bearer $ACCESS_TOKEN' \
   -H 'Content-Type: application/json' \
   -d --data @body.json

In the body.json file, the JSON payload should contain the following parameters:

• type (string, required): Indicates the order's type of request. To change SIM profiles, use "change_sim_profile".
• account_id (string, required): Identifies the account where the SIM change will be triggered and it can be obtained via Accounts API.
• subscription_id (string, required): Identifies the existing subscription to which the SIM change will be applied.
• sim_type (string, required): Type of the new SIM profile. The only valid value is "esim".
• type (string, required if sim_type is "esim"): Method of QR code delivery. The only valid value at the moment is "email".
• to (array of strings, required if sim_type is "esim"): Email addresses where the new eSIM QR code will be sent to.

Example request body.json:

{
    "type": "change_sim_profile",
    "account_id": "acc_01AAAABBE00AAAA8AABAA4R37A",
    "subscription_id": "sub_01AAAA1AA1A11AA1AA1A11196X9",
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.doe@star-industries.com"]
        }
    }
}

Initial Response

Upon successful submission, the API responds with an initial order ID and status. The status is set to "pending", indicating that processing has begun.

Example Initial Response:

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "pending",
    "type": "change_sim_profile",
    "account_id": "acc_01DKVAGTE00ECXW8AYBVB4R37Q",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.doe@stark-industries.com"]
        }
    },
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

Asynchronous Processing

Due to the asynchronous nature of the order processing, it is required to implement logic to periodically check the order status. Clients should query the status of their order using the GET /orders/{orderId}\ endpoint. The final order status can be "completed" or "cancelled". Implement a polling mechanism to monitor status changes until the order reaches a final state.

Example GET Request:

curl -X GET \
  https://api.1global.com/enterprise/orders/order_01HZS5KETGM8XXF53WZJWDDV4C \
   -H 'Authorization: Bearer $ACCESS_TOKEN' \
   -H 'Content-Type: application/json' 

note

The provisioning actions usually require a few minutes to complete. However, it is possible that ocasionally some requests could take longer, depending on resources availability.

Receive New eSIM QR Code

When the order status transitions to "completed" the API automatically sends the new eSIM QR code to the specified email addresses. This includes the primary email (email) and any CC email (ccEmail) provided during the request submission. When the provisioning actions are finished, you'll also get the resulting Subscriptions identifier (subscription_id).

note

Upon completion of the order, the previous SIM associated with the subscription will be terminated.

Example Response when order is completed:

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "completed",
    "type": "change_sim_profile",
    "account_id": "acc_01DKVAGTE00ECXW8AYBVB4R37Q",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "sim_profile": {
        "sim_type": "esim",
        "iccid": "8944478100000780801",
        "delivery": {
            "type": "email",
            "to": ["j.doe@stark-industries.com"]
        }
    },
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

note

Although not likely to happen, the status=cancelled exists to accomodate any unforseen event that makes it impossible to fulfill your request. Your Account Manager will be able to provide you additional info.