Buy eSIM top-up
curl --request POST \
--url https://api.withallo.com/v2/api/partner/esims/{id}/topups \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"code": "TOPUP_5GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload = { "code": "TOPUP_5GB" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({code: 'TOPUP_5GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/topups', 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}/topups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'TOPUP_5GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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}/topups"
payload := strings.NewReader("{\n \"code\": \"TOPUP_5GB\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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.post("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"TOPUP_5GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"TOPUP_5GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"code": "TOPUP_5GB",
"data_mb": 5120,
"status": "PENDING"
}
}{
"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
Buy eSIM top-up
Buys a data top-up for an eSIM. The top-up is charged once: Allo draws on your prepaid credit first, then charges your card on file. Its data is added to the eSIM once the payment is confirmed, for the current calendar month (Paris time). Unused data lapses at the end of that month. The Idempotency-Key header is required: send a new UUID for each top-up and the same one when you retry it. A card that requires 3D Secure is refused with ESIM_PAYMENT_FAILED and the attempt is cancelled. Only the number’s latest eSIM can be topped up. Requires the PARTNER scope.
POST
/
v2
/
api
/
partner
/
esims
/
{id}
/
topups
Buy eSIM top-up
curl --request POST \
--url https://api.withallo.com/v2/api/partner/esims/{id}/topups \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"code": "TOPUP_5GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload = { "code": "TOPUP_5GB" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({code: 'TOPUP_5GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/topups', 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}/topups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'TOPUP_5GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$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}/topups"
payload := strings.NewReader("{\n \"code\": \"TOPUP_5GB\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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.post("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"TOPUP_5GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"TOPUP_5GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"code": "TOPUP_5GB",
"data_mb": 5120,
"status": "PENDING"
}
}{
"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:
PARTNERpartner.esim.data_low at 80% of the allowance and partner.esim.data_exhausted at 100%, so you can offer your client a top-up in time.
Request
- The
Idempotency-Keyheader is required: see Retries. codeis required: atop_ups[].codefrom Get eSIM offer.- The eSIM must be
ACTIVE. While it is still provisioning, the request fails withESIM_NOT_READY.
code | Data added |
|---|---|
TOPUP_5GB | 5 GB (5120 MB) |
TOPUP_10GB | 10 GB (10240 MB) |
TOPUP_20GB | 20 GB (20480 MB) |
INVALID_ESIM_TOPUP. You can buy several top-ups for the same eSIM in the same month: their data adds up.
Response
status | What it means |
|---|---|
PENDING | Allo charged the top-up. Its data is added to the eSIM once the payment is confirmed, and Get eSIM then shows it in data.allowance_mb. |
ACTIVE | A retry with the same Idempotency-Key of a top-up already added. Nothing is charged again. |
Billing
- The price is the one Get eSIM offer returns for the account: before tax, in the currency of the subscription you pay for the account.
- 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 top-up 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.
Retries
TheIdempotency-Key header is required on this endpoint, so a retry can never charge you twice. Send a new UUID for each top-up, and the same one when you retry that top-up.
- Without the header, the request fails with
400 IDEMPOTENCY_KEY_REQUIRED. - The key is 8 to 100 letters, digits,
-or_. A key in another format fails with400 INVALID_IDEMPOTENCY_KEY. - A key already used on this eSIM for a top-up with another
codefails with409 IDEMPOTENCY_KEY_ALREADY_USED. Send a new key for a new top-up.
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_TOPUP_PENDING | Another top-up for this eSIM is still being paid. Always retryable: true. Retry in a few minutes, or resume the earlier purchase with its Idempotency-Key. |
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
Was this page helpful?