Skip to main content

Add new Subscription

The Orders API allows organizations to self-manage their subscriptions by provisioning new eSIM profiles based on templates containing predefined bundle of services (data, voice, SMS, recording settings, etc). These templates are tailored to each account and must be obtained direcly from the Support Delivery Manager.

Two eSIM delivery methods are currreny available:

  • Email Delivery: The QR code is sent via email directly to the specified email recipients.
  • QR Code Retrieval: The QR code is generated and must be retrieved via a separate API call.
  • Push Notification via EID: The eSIM is delivered directly to the device using the subscriber’s EID (eUICC identifier). The subscriber will see a system notification on their device prompting them to download and install the new eSIM profile. This method is currently only available for apple devices.

Submit an Order​

To initate the subscription suspension, send a HTTP POST request to the endpoint below:

POST  https://api.1global.com/enterprise/orders

Ensure the request includes the following headers:

For more details on setting up the headers, refer to Making Your First Request.

Option 1: Email Delivery​

For this delivery method the delivery.type must be "email".

{
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTEST",
    "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XTEST",
    "subscriber": {
        "first_name": "John",
        "last_name": "Jordan",
        "email": "j.jordan@star-industries.com",
        "employee_id": "12345",
        "group": "finance"
    },
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.jordan@star-industries.com"], 
            "cc": ["a.peterson@star-industries.com"]
        }
    }
}

Option 2: QR Code Only (API Retrieval)​

For this delivery method, the delivery.type must be "api".

{
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTEST",
    "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XTEST",
    "subscriber": {
        "first_name": "John",
        "last_name": "Jordan",
        "email": "j.jordan@star-industries.com",
        "employee_id": "12345",
        "group": "finance"
    },
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "api"
        }
    }
}

Option 3: Push Notification via EID​

For this delivery method, the delivery.type must be "smds".

{
  "type": "activate_subscription",
  "account_id": "acc_00DKABCDE12ECXW8AYBVBTEST",
  "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XTEST",
  "subscriber": {
    "first_name": "John",
    "last_name": "Jordan",
    "email": "j.jordan@star-industries.com",
    "employee_id": "12345",
    "group": "finance"
  },
  "sim_profile": {
    "sim_type": "esim",
    "delivery": {
      "type": "smds",
      "smds": "apple",
      "eid": "89049032000001000000012345678901"
    }
  }
}

API Response​

Upon successful submission on both cases, the API returns an Order ID and the status pending, indicating that the order processing has begun.

Example Response - Email Delivery

{
    "id": "order_01HZS5KETGM8XXF53WZJWDTEST",
    "status": "pending",
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTEST",
    "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XTEST",
    "subscriber": {
        "first_name": "John",
        "last_name": "Jordan",
        "email": "j.jordan@star-industries.com",
        "employee_id": "12345",
        "group": "finance"
    },
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "email",
            "to": ["j.jordan@star-industries.com"],
            "cc": ["a.peterson@star-industries.com"]
        }
    },
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDTEST"
        }
    }
}

Monitor Order Status​

Provisioning is asynchronous, meaning the order must be monitored until it is either completed or cancelled. This applies to all delivery methods: Email, QR Retrieval, and SMDS (Apple devices).

Workflow

  • Submit Order - The order is created with status pending.

  • Poll Order Status - Send a GET request until the status changes to completed or cancelled.

  • Completion Handling - Once the order is completed, the provisioning outcome depends on the delivery type:

    • Email Delivery - QR code is sent via email to the recipient’s inbox.
    • SMDS - subscriber’s device shows a system notification prompting them to install the new eSIM profile.
    • QR Code Only - QR code must be retrieved using the /enterprise/qr-codes/qr_code_id endpoint.

Check Order Status​

Send a GET request to check the current status of the order:

GET  https://api.1global.com/enterprise/orders/{order_Id}

Replace order_Id with the unique order ID received from the initial response (e.g., order_01HZS5KETGM8XXF53WZJWDTEST).

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

Example Response - QR Code (API Retrieval)

{
    "id": "order_01HZS5KETGM8XXF53WZJWDTEST",
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTEST",
    "status": "completed",
    "subscriber": {
        "first_name": "Test",
        "last_name": "Session",
        "email": "byte@size.com",
        "employee_id": "",
        "group": ""
    },
    "sim_profile": {
        "sim_type": "esim",
        "delivery": {
            "type": "api"
        }
    },
    "subscription_id": "sub_01AA111122222222233333444444",
    "_links": {
        "esim_qr_code": {
            "href": "https://api.1global.com/enterprise/qr-codes/qr_0000000001111111AAAAAAABBBB"
        },
        "self": {
            "href": "https://api.1global.com/enterprise/orders/order_0000000001111111AAAAAAABBBB"
        }
    }
}

For the API Delivery method, fetch the QR code by calling:

GET  https://api.1global.com/enterprise/qr-codes/{qr_code_id}

Replace the qr_code_id with the ID from the response.

note

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