Skip to content
Roamex API

Cancel an eSIM

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

Cancels an eSIM that has not been used and credits your balance; refund states the amount. For a provisioned eSIM the status is checked live before anything is cancelled. A cancelled eSIM cannot be restored.

Authorizations

Section titled “Authorizations”

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 eSIM is cancelled and your balance is credited.

Media typeapplication/json
object
success
required
boolean
cancelled
required
boolean
refund
required

The amount credited to your balance.

object
amount
required

Euro cents.

integer
currency
required
string
Allowed values: EUR
formatted
required
string
newBalance
required
object
amount
required

Euro cents.

integer
currency
required
string
Allowed values: EUR
formatted
required
string
message
required
string

Example 

{
  "success": true,
  "cancelled": true,
  "refund": {
    "amount": 450,
    "currency": "EUR",
    "formatted": "€4.50"
  },
  "newBalance": {
    "amount": 24550,
    "currency": "EUR",
    "formatted": "€245.50"
  },
  "message": "eSIM cancelled. €4.50 refunded to your balance."
}

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.
  • ALREADY_CANCELLED: the eSIM is already cancelled.
  • CANNOT_CANCEL: the eSIM is spent or no longer exists on the network.
  • CANNOT_CANCEL_ACTIVE: the eSIM has used data or has connected to a network.
  • NO_ORDER_REFERENCE: the eSIM has no order reference to cancel with.
  • CUSTOMER_TOPUP_EXISTS: the traveller paid for top-ups on this eSIM that were delivered.
  • NOTHING_TO_CREDIT: what this eSIM cost your balance was already returned.
  • STOREFRONT_ESIM: this eSIM was not charged to your balance.
  • CANCEL_FAILED: the cancel was refused. Nothing changed.
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”
  • SHOP_ORDER_IN_FLIGHT: the shop order this eSIM belongs to is still open. Nothing was cancelled.
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”
  • REFUND_FAILED: the eSIM was cancelled but the credit to your balance failed. Roamex has been notified and reconciles it.
  • INTERNAL_ERROR, or AUTH_ERROR with status 500: see the shared errors.
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”

Nothing was credited.

  • STATUS_UNVERIFIED: the eSIM’s current status could not be verified. Retry with backoff.
  • TOPUP_CHECK_UNAVAILABLE: the traveller’s top-ups could not be checked. Retry with backoff.
  • CANCEL_CHECK_UNAVAILABLE: what this eSIM cost your balance could not be read. Retry with backoff.
  • CANCEL_FAILED: the cancel could not be completed and nothing changed. Retry with backoff.
  • CANCEL_OUTCOME_UNKNOWN: it is not known whether the eSIM was cancelled. Roamex checks it by hand. Do not retry.
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
}