List plans

POST

/plans

const url = 'https://api.roamex.com/v1/plans?lang=nl';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"region":"JP","type":"one-time","page":1,"limit":20}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.roamex.com/v1/plans?lang=nl' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "region": "JP", "type": "one-time", "page": 1, "limit": 20 }'

Lists the plans you can buy through the API at your price, cheapest first. Filter by country code or region slug, plan type and data size; a page holds up to 100 plans. A page past the end returns an empty plans list with total 0, so read total from a page that has plans.

Authorizations

apiKey

Parameters

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 Body

Optional. An empty body lists every plan, 50 per page.

application/json

object

region

A 2-letter country code, or a slug from /regions. A country code also matches regional plans that include that country. Characters other than letters, digits, _ and - are removed first, and the rest must be 1 to 50 characters. An unknown region slug returns 400 INVALID_REGION; a country code with no plans returns an empty list. A non-string value is ignored.

string

type

one-time for fixed-data plans, unlimited for day passes. Any other value returns 400 INVALID_TYPE.

string

Allowed values: one-time unlimited

minData

Smallest data amount, in bytes. A numeric string is accepted. A negative value is ignored. A value that is not a number returns 400 INVALID_MIN_DATA.

number | string

maxData

Largest data amount, in bytes. A numeric string is accepted. A negative value is ignored. A value that is not a number returns 400 INVALID_MAX_DATA.

number | string

page

Page number. A missing or non-numeric value means 1.

integer

default: 1 >= 1

limit

Plans per page. A missing or non-numeric value means 50; larger values are lowered to 100.

integer

default: 50 >= 1 <= 100

Example

{
  "region": "JP",
  "type": "one-time",
  "page": 1,
  "limit": 20
}

Responses

200

A page of plans.

application/json

object

success

required

boolean

plans

required

Array<object>

object

required

Use as planId.

string format: uuid

name

required

string

region

required

object

code

required

A country code, or a comma-separated list of country codes for a regional plan.

string | null

name

required

string

countries

required

The country codes the plan covers.

Array<string>

isRegional

required

boolean

data

required

Any of:

object
object

object

bytes

required

0 when unknown.

integer

formatted

required

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

string

A day pass.

object

unlimited

required

boolean

perDay

required

The full-speed data per day.

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

Your price. For a fixed-data plan it is what /esims/purchase charges per eSIM. For a day pass it is a one-day rate, with perDay and note; the total for several days is not this rate times the days, and /esims/purchase returns it.

object

amount

required

Euro cents.

integer

currency

required

string

Allowed values: EUR

formatted

required

string

perDay

Present on day passes only.

boolean

note

Present on day passes only.

string

type

required

unlimited is a day pass.

string

Allowed values: one-time unlimited

supportsTopUp

required

Whether eSIMs of this plan can be topped up.

boolean

activation

required

object

startsOn

required

When the validity period starts: at installation on a device, or at the first connection to a network. null when unknown.

string | null

Allowed values: installation first_connection

activateWithinDays

required

The plan must be activated within this many days. null when unknown.

integer | null

pagination

required

object

page

required

integer

limit

required

integer

total

required

Matching items across all pages.

integer

totalPages

required

integer

Example

{
  "success": true,
  "plans": [
    {
      "id": "00000000-0000-4000-8000-0000000000b1",
      "name": "Japan · 1 GB · 7 days",
      "region": {
        "code": "JP",
        "name": "Japan",
        "countries": [
          "JP"
        ],
        "isRegional": false
      },
      "data": {
        "bytes": 1073741824,
        "formatted": "1.00 GB"
      },
      "validity": {
        "days": 7,
        "unit": "DAY"
      },
      "price": {
        "amount": 450,
        "currency": "EUR",
        "formatted": "€4.50"
      },
      "type": "one-time",
      "supportsTopUp": true,
      "activation": {
        "startsOn": "first_connection",
        "activateWithinDays": 180
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

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

INVALID_JSON: the body is not a JSON object.
INVALID_REGION: region is not a known country code or region slug.
INVALID_TYPE: type is not one-time or unlimited.
INVALID_MIN_DATA: minData is not a number of bytes.
INVALID_MAX_DATA: maxData is not a number of bytes.

application/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": "INVALID_TYPE",
    "message": "Unknown type. Use 'one-time' or 'unlimited'."
  }
}

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.

application/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

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

application/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

NOT_FOUND: the API is switched off on the platform. Every endpoint answers this before the key is checked, with the message This feature is not available.

application/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": "NOT_FOUND",
    "message": "This feature is not available."
  }
}

413

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

application/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

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.

application/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

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

DATABASE_ERROR: the plans could not be read.
INTERNAL_ERROR, or AUTH_ERROR with status 500: see the shared errors.

application/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

Transient. Retry with backoff.

PRICING_UNAVAILABLE: your account pricing could not be confirmed.
REGION_LOOKUP_FAILED: the region slug could not be resolved.

application/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
}