Top up an eSIM profile

How to add a new product to an already activated eSIM profile via Connect.

1. Placing the Order

Topping up will allow binding another plan to an already existing eSIM profile. As in an initial activation this flow happens through the order API. The order request will include the ID of the product that will be activated via the order, check the Product Catalogue guide in order to understand how to access the product catalogue. Additionally, for the topup of an eSIM profile the order request also needs to include the iccid of the profile that shall be topped up.

Example Request

curl -X POST \  https://services.truphone.com/connect-api/v2/orders \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H 'Cache-Control: no-cache' \  -H 'Content-Type: application/json' \  -H 'X-Correlation-ID: unique-id-from-requester-123' \  -d '{      "operation_type": "TOPUP",      "sim_type": "ESIM",      "country": "GB",      "product": {        "id": "kn8etk9XBX0gG7pFP5KErXvWVNN4jOERTMVMNEkX-Ak="      },      "subscriber": {        "device": {          "operating_system": "ios",          "model": "iPhone",          "id": "1234567"        },        "sim": {          "iccid": "8944472600000510740"        }      }}'

Example Response

{  "id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",  "status": "ACCEPTED",  "created_date": "2020-01-01T00:00:00Z",  "_metadata": {    "_links": {      "_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"    }  }}

When placing an order, you can set a customised activation and expiration date. If no activation date has been provided, the subscription will be created and activated automatically. On the other hand, if no expiration date has been provided, the subscription will be calculated based on the duration of the plan. Note that this expiration date cannot be longer than the duration of the selected plan and that making it shorter will not change any other plan settings, such as price or data allowance.

2. Checking the Order status

Order fulfilment is not synchronous, so after placing an order, the order status needs to be periodically checked until completion using a polling mechanism. For this your code can use the order API or just use the metadata links available in the response from order creation. You can find the full list of order status here.

Example Request

curl -X GET \  https://services.truphone.com/connect-api/v2/orders/3a6acf89-1ccf-4611-9424-453930f57ef1 \   -H "Authorization: Bearer $ACCESS_TOKEN" \   -H 'Cache-Control: no-cache' \   -H 'Content-Type: application/json' \   -H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response

{  "id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",  "status": "COMPLETED",  "created_date": "2021-02-24T09:00:00Z",  "output": {    "iccid": "8944000013283712983321",    "subscription_id": "Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE="  },  "_metadata": {    "links": {      "_sim": "{BASE_URL}/v2/sims/8944000013283712983321",      "_subscription": "{BASE_URL}/v2/subscriptions/Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE=",      "_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"    }  }}

3. Installing the eSIM

In most cases topping up means the eSIM profile is already installed in a device meaning the new plan will start working right away. If more information on how to install an eSIM profile is required please check the following section