Skip to content
Roamex API

Get plan details

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

Returns one plan with your price and, for a regional plan, the countries it covers. Plans that /plans leaves out because a better plan replaces them, or because they are not listed on the API, still resolve here.

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
planId
required

A plan id from /plans.

string format: uuid

Example 

{
  "planId": "00000000-0000-4000-8000-0000000000b1"
}

Responses

Section titled “Responses”

200

Section titled “200”

The plan.

Media typeapplication/json
object
success
required
boolean
plan
required
object
id
required
string format: uuid
name
required
string
region
required
object
code
required
string | null
name
required
string
isRegional
required
boolean
countries

Regional plans only.

Array<object>
object
code
required
string
name
required
string
data
required
Any of:
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
configurable
required

true for a day pass: you choose the days with days on /esims/purchase.

boolean
minDays

Day passes only. Always 1.

integer
maxDays

Day passes only. Always 60.

integer
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
string
Allowed values: one-time unlimited
supportsTopUp
required
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

Example 

{
  "success": true,
  "plan": {
    "id": "00000000-0000-4000-8000-0000000000b2",
    "name": "Japan · Unlimited (2 GB/day)",
    "region": {
      "code": "JP",
      "name": "Japan",
      "isRegional": false
    },
    "data": {
      "unlimited": true,
      "perDay": {
        "bytes": 2147483648,
        "formatted": "2.00 GB"
      }
    },
    "validity": {
      "days": 1,
      "unit": "DAY",
      "configurable": true,
      "minDays": 1,
      "maxDays": 60
    },
    "price": {
      "amount": 290,
      "currency": "EUR",
      "formatted": "€2.90",
      "perDay": true,
      "note": "Per-day rate (1-day price). Multi-day totals are discounted (not price × days) and capped at 60 days; call /esims/purchase for the exact total."
    },
    "type": "unlimited",
    "supportsTopUp": true,
    "activation": {
      "startsOn": "first_connection",
      "activateWithinDays": 180
    }
  }
}

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_PLAN_ID: planId is missing.
  • PLAN_NOT_AVAILABLE: the plan has no price.
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”
  • PLAN_NOT_FOUND: no active, sellable plan has this id.
  • 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
}

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.

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