Skip to main content

Add new Subscription

Preview

The Order API is designed to streamline the creation of new subscriptions for clients, allowing them to submit provisioning requests efficiently. By submitting an order with all necessary details, the API simplifies the provisioning process, making it easier for our clients to manage their subscriptions. For more details, visit the API Reference.

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 an Order​

Clients initiate the process by sending a POST request to the https://api.1global.com/enterprise/orders endpoint. The request includes the necessary details encapsulated in a JSON payload structured as follows:

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 this crucial parameters:

  • account_Id (string, required): Identifies the account where the subcription will be provisioned.
  • first_Name (string, required): First name of the user.
  • last_Name (string, required): Last name of the user.
  • group (string, optional): Group code associated with the subscription and defined by the client to categorize users.
  • email (string, required): Email address of the user.
  • employee_id (string, optional): Employee ID of the user.
  • template_id (string, required): Specifies the template ID, defining the combination of plans and products. These templates are customized for each customer and must be obtained from the Account Manager.
  • to (string, required): Email address where the eSIM QR code will be sent.
  • cc (string, optional): Additional email address to receive a copy of the eSIM QR code.

Example 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"]
        }
    }
}

Order Accepted​

Upon sucessfull submission the API responds with:

{
    "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 such as the order ID, status, template ID, subscriber information, and delivery emails for the eSIM QR code.

note

Since the request triggers an assynchronous process, you'll get an immediate result with status = "pending".

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.

Check Order Status​

It is possible to monitor the progress of the order by querying the status using the GET /orders/{orderId} endpoint. 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'

Example response when the order is still processing (status: "pending"):

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

Completed Order​

Continue polling the order status periodically. Once the order status changes to "completed", the eSIM provisioning is finished. The response will include the eSIM details, such as the ICCID (e.g: 8944478100000780801), Subscriptions identifier (subscription_id) and the delivery emails.

{
    "id": "order_01HZS5KETGM8XXF53WZJWDDV4C",
    "status": "completed",
    "type": "activate_subscription",
    "account_id": "acc_00DKABCDE12ECXW8AYBVBTT00",
    "subscription_id": "sub_01DRGT6VG8C79TX5CW1W9696X9",
    "subscriber": {
        "id": "per_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"
        }
    }
}
warning

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.