Version: v2.0

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

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 fin 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