Change eSIM tier
curl --request PUT \
--url https://api.withallo.com/v2/api/partner/esims/{id}/tier \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"tier": "ESIM_20GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/tier"
payload = { "tier": "ESIM_20GB" }
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({tier: 'ESIM_20GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/tier', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/esims/{id}/tier",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'tier' => 'ESIM_20GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}/tier"
payload := strings.NewReader("{\n \"tier\": \"ESIM_20GB\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.withallo.com/v2/api/partner/esims/{id}/tier")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tier\": \"ESIM_20GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/tier")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tier\": \"ESIM_20GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"tier": "ESIM_20GB",
"status": "PENDING",
"effective_at": null
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}eSIM
Change eSIM tier
Moves an eSIM to another data tier. An upgrade is charged now, prorated for the rest of the billing period: Allo draws on your prepaid credit first, then charges your card on file. The extra data is added within about a minute once the payment is confirmed. A downgrade is scheduled for the end of the period already paid, and nothing is refunded. A card that requires 3D Secure is refused with ESIM_PAYMENT_FAILED and the attempt is cancelled. Only the number’s latest eSIM can change tier. Requires the PARTNER scope.
PUT
/
v2
/
api
/
partner
/
esims
/
{id}
/
tier
Change eSIM tier
curl --request PUT \
--url https://api.withallo.com/v2/api/partner/esims/{id}/tier \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"tier": "ESIM_20GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/tier"
payload = { "tier": "ESIM_20GB" }
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({tier: 'ESIM_20GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/tier', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/esims/{id}/tier",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'tier' => 'ESIM_20GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}/tier"
payload := strings.NewReader("{\n \"tier\": \"ESIM_20GB\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.withallo.com/v2/api/partner/esims/{id}/tier")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tier\": \"ESIM_20GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/tier")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tier\": \"ESIM_20GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"tier": "ESIM_20GB",
"status": "PENDING",
"effective_at": null
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}Required scope:
PARTNERRequest
tieris required: atiers[].codefrom Get eSIM offer, for exampleESIM_20GB.ESIMis the tier with no mobile data. An unknown code fails withINVALID_ESIM_TIER.- The eSIM must be
ACTIVE. While it is still provisioning, the request fails withESIM_NOT_READY.
Response
status | What it means |
|---|---|
ACTIVE | The eSIM is already on this tier. Nothing is charged. |
PENDING | Upgrade. Allo charges it now, and the extra data is added within about a minute once the payment is confirmed. |
SCHEDULED | Downgrade. The eSIM keeps its current tier until effective_at, the end of the period already paid, then switches to the new tier. Nothing is refunded. |
effective_at is null unless status is SCHEDULED. Get eSIM returns the current tier, the scheduled downgrade in scheduled_tier and scheduled_tier_at, and the month’s allowance in data.allowance_mb.
An upgrade raises the allowance, so partner.esim.data_low and partner.esim.data_exhausted can be sent again as the eSIM nears the new allowance.
Billing
- An upgrade is charged on the subscription you pay for the account, prorated for the rest of the current billing period, with your partner discount applied. The subscription then renews at the new tier’s price.
- Allo draws on your prepaid credit first, then charges your card on file for the rest. Allo never charges your client.
- If your prepaid credit does not cover the upgrade and you have no card on file, the request fails with
402 PARTNER_CREDIT_INSUFFICIENT. - A declined card, or a card that requires 3D Secure, fails with
402 ESIM_PAYMENT_FAILED. A 3D Secure check cannot happen over the API, so Allo cancels the attempt and nothing stays pending. Retry with another card, updated in the partner portal, or after you top up your prepaid credit. - A downgrade charges nothing and refunds nothing.
Retries
Send anIdempotency-Key header (8 to 100 letters, digits, - or _, for example a UUID) and reuse it when you retry the same change. Retrying with the same key does not charge you twice. A key in another format fails with INVALID_IDEMPOTENCY_KEY.
Errors specific to this eSIM
| Code | What it means |
|---|---|
ESIM_NOT_READY | The eSIM is still provisioning. Wait for partner.esim.ready, then retry. |
ESIM_NOT_ACTIVE | The eSIM was deleted, or the number has a newer eSIM order. Only the number’s latest eSIM can be changed: use its id, or order a new eSIM with Order eSIM. |
ESIM_TIER_CHANGE_CONFLICT | A downgrade is already scheduled for this eSIM. It cannot be replaced until it applies, at scheduled_tier_at. |
ESIM_SUBSCRIPTION_CONFLICT | The subscription you pay for the account cannot be charged for eSIMs right now. When the error is retryable: true, retry in a few minutes. |
Headers
Body
application/json
Was this page helpful?