Skip to main content

Orders

Preview

The Orders API enables organizations to create new or change existing subscriptions by providing the details to 1GLOBAL. This helps organizations to change physical SIM associated with an existing subscription to eSIM. This helps organizations create orders efficiently and manage their subscriptions.

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

How it works​

This API streamlines the provisioning and management of subscription orders for organizations as follows:

The below table depicts the statuses for an order.

StatusDescription
pendingSuccessfully accepted and processing the order.
completedeSIM provisioning is accomplished.
canceledUnable to process the order.

Submit an Order​

Send an HTTP POST request to 1GLOBAL to:

  • order a new subscription with the specified subscription details (use "type": "activate_subscription")
  • replace the SIM associated with the existing subscription, for changing physical SIM to eSIM. (use "type": "change_sim_profile" )
POST https://api.1global.com/enterprise/orders

The request includes the necessary details encapsulated in a JSON payload structure to submit an order.

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

Example Request Body:​

Specify the subscription details (specifically the mandatory fields) in the request body, refer API Reference to understand the request body.

{
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTT000",
    "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XQFUT",
    "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"]
        }
    }
}

Example Response​

Order Accepted: Upon successful submission the API responds with status pending:

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "pending",
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTT00",
    "template_id": "otpl_A00ABCDRT1F00AVRPTAQ5XQFUT",
    "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_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

This includes details like order ID, status, template ID, subscriber information, and delivery emails for the eSIM QR code.

[!NOTE] Since the request triggers an asynchronous process, you'll get an immediate result with status = pending. Provisioning actions take a few minutes to complete. However, some requests may occasionally take longer, depending on resource availability.

Check Order Status​

Send an HTTP GET request to 1GLOBAL to monitor the progress of the order you placed using Submit an Order API. Specify the unique order identifier that was returned while creating the order.

POST https://api.1global.com/enterprise/orders/{order_id}

You must implement logic to handle the asynchronous nature of the process and query the status using the GET /orders/{orderId} endpoint:

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

**Order Completed ** Continue polling the order status periodically. As order status changes to completed, the eSIM provisioning is accomplished. The response includes the eSIM details, such as the ICCID (e.g: 8944478100000780801), Subscriptions identifier (subscription_id) and the delivery emails. Example response when the order is status=completed:

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "completed",
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTT00",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "subscriber": {
        "id": "sbr_01HF9SHB00WDFA5VT2JTME7YCK",
        "first_name": "John",
        "last_name": "Jordan",
        "email": "j.jordan@star-industries.com",
        "employee_id": "12345",
        "group": "finance"
    },
    "sim_profile": {
        "sim_type": "esim",
        "iccid": "8944478100000780801",
        "delivery": {
            "type": "email",
            "to": ["j.jordan@star-industries.com"],
            "cc": ["a.peterson@star-industries.com"]
        }
    },
    "phone_numbers": [
        {
            "msisdn": "123456789",
            "is_primary": "true",
            "country": "US"
        },
        {
            "msisdn": "987654321",
            "is_primary": "false",
            "country": "UK"
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.staging.1global.com/ordering/orders/orders/order_01HZS5KETGM8XXF53WZJWDDV4C"
        }
    }
}

[!IMPORTANT]
Although not likely to happen, the status=canceled exists to accommodate any unforseen event that makes it impossible to fulfill your request. Your Account Manager can provide you additional info.