Skip to content
Roamex API

List top-up options

POST
/esims/topup-options
curl --request POST \
  --url 'https://api.roamex.com/v1/esims/topup-options?lang=nl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "esimId": "00000000-0000-4000-8000-0000000000c1" }'

Lists the top-up packages you can add to an eSIM, at your price, cheapest first. Pass a package id as packageId to /esims/topup; the ids change on every call. Day-pass extensions are not offered through the API.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
lang
string
default: en

Language of plan and destination names in the response: en, nl, es, de, it, fr, pl, pt, tr, el, cs or ro. Any other value, or none, gives English. It never changes which items are returned or any figure.

Example 

nl

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
esimId
required

An eSIM id from /esims/purchase or /esims/list.

string format: uuid

Example 

{
  "esimId": "00000000-0000-4000-8000-0000000000c1"
}

Responses

Section titled “Responses”

200

Section titled “200”

The packages. The list can be empty.

Media typeapplication/json
object
success
required
boolean
esim
required
object
id
required
string format: uuid
planName
required
string
region
required

The eSIM’s destination name.

string
packages
required

Cheapest first.

Array<object>
object
id
required

Pass as packageId to /esims/topup. A new token on every call.

string
name
required

Named after the eSIM’s own destination.

string
region
required

The package’s own coverage, which can differ from the eSIM’s destination.

object
code
required
string | null
name
required
string
data
required
object
bytes
required

0 when unknown.

integer
formatted
required

Two decimals in GB, whole numbers in MB and KB, 0 B when unknown.

string
validity
required
object
days
required
integer | null
unit
required
string
price
required

What /esims/topup charges for this package.

object
amount
required

Euro cents.

integer
currency
required
string
Allowed values: EUR
formatted
required
string

Example 

{
  "success": true,
  "esim": {
    "id": "00000000-0000-4000-8000-0000000000c1",
    "planName": "Japan · 1 GB · 7 days",
    "region": "Japan"
  },
  "packages": [
    {
      "id": "pkg_EXAMPLE.TOKEN.VALUE",
      "name": "Japan · 1 GB · 7 days",
      "region": {
        "code": "JP",
        "name": "Japan"
      },
      "data": {
        "bytes": 1073741824,
        "formatted": "1.00 GB"
      },
      "validity": {
        "days": 7,
        "unit": "DAY"
      },
      "price": {
        "amount": 450,
        "currency": "EUR",
        "formatted": "€4.50"
      }
    }
  ]
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining
integer

Calls left in the current minute.

X-RateLimit-Reset
integer

When the current window ends, in Unix seconds.

400

Section titled “400”
  • INVALID_JSON: the body is missing or not a JSON object.
  • MISSING_ESIM_ID: esimId is missing.
  • ESIM_CANCELLED: the eSIM is cancelled.
  • ESIM_NOT_READY: the eSIM is not provisioned yet.
  • NO_TOPUP_OPTIONS: no top-up packages are available for this eSIM.
  • UNSUPPORTED_PACKAGE: the only packages available are day-pass extensions, which the API does not sell.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

401

Section titled “401”

AUTH_ERROR: the key is missing, malformed, unknown or revoked. The message says which, for example Missing Authorization header, Invalid Authorization header format. Use: Bearer <api_key>, Invalid API key format or Invalid API key.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "AUTH_ERROR",
    "message": "Invalid API key"
  }
}

403

Section titled “403”

AUTH_ERROR: the account is suspended (Your account is suspended. Please contact support.) or rejected (Account is not approved for API access).

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

404

Section titled “404”
  • ESIM_NOT_FOUND: no eSIM with this id belongs to your account.
  • NOT_FOUND: the API is switched off on the platform.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

409

Section titled “409”
  • ESIM_EXPIRED: the eSIM’s validity has ended.
  • TOPUP_LIMIT_REACHED: the eSIM already has 9 top-ups, the most it accepts. Order a new eSIM instead.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

413

Section titled “413”

PAYLOAD_TOO_LARGE: the Content-Length header is over 100 KB.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

429

Section titled “429”

RATE_LIMITED: the account’s per-minute budget for this endpoint group is used up, or too many refused keys came from this IP address. Wait the Retry-After seconds.

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please wait 42 seconds before retrying."
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Calls allowed per minute for this endpoint group.

X-RateLimit-Remaining
integer

Calls left in the current minute.

X-RateLimit-Reset
integer

When the current window ends, in Unix seconds.

Retry-After
integer

Seconds to wait before retrying.

500

Section titled “500”
  • INTERNAL_ERROR: an unexpected error on our side.
  • AUTH_ERROR with status 500: the key could not be checked because of an error on our side. Retry with backoff.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}

503

Section titled “503”

Transient. Retry with backoff.

  • TOPUP_OPTIONS_UNAVAILABLE: the top-up options could not be loaded.
  • PRICING_UNAVAILABLE: your account pricing could not be confirmed.
Media typeapplication/json
object
success
required
boolean
error
required
object
code
required

Machine-readable. Branch on this.

string
message
required

A sentence for people. It can change.

string

Example 

{
  "success": false
}