eSIM

POST/v1/esim/orders

Order an eSIM — who pays follows your key

What this call does depends on the settlement mode of the key you present, and on nothing else. It is not a choice per request: sending settlement in the body is a CHECK, and a value that contradicts your key is refused rather than obeyed.

**partner settlement (mode A).** You are the merchant. We reserve the net price on your account, order from the supplier, then charge what was actually due — three steps, inside this one call. If the supplier declines, the reservation is released and you are not charged. You get the eSIM back provisioned, checkout is null, and you have already invoiced your own customer.

**vacabee settlement (mode B).** WE are the merchant and your TRAVELLER pays us. Your account is never touched — there is no reservation, no charge and no 402. The order comes back at AWAITING_PAYMENT with a checkout.url: send your traveller there. Nothing is bought at the supplier until he has paid, so nothing is held for him either — the link carries a price with a deadline, and letting it run out is an ordinary outcome, not a fault. You are told either way through the esim.provisioned / esim.failed webhooks.

402 insufficient_funds and 403 account_not_active can only reach a partner key: they are answers about an account that mode B does not use.

Auth: API key
Scope: esim:order
Rate limit: BOOKING
Search quota: Free
Idempotency: Idempotency-Key

Request headers

Header	Type	Required	Description	Example
`Idempotency-Key`	`string`	Required	Mandatory on every POST. The same request with the same key returns the stored response without reaching the supplier again. The same key with a DIFFERENT body is rejected with `409 idempotency_key_reuse`. Retained for 24 hours.	`4f1c358f-6b2e-5acb-8ef5-0c3d0bcc35f5`

Request body

CreateEsimOrderDto — required, sent as application/json.

Responses

201 · EsimOrderDto

Errors

Every one of these carries the same envelope. What each error.type means, and whether a retry can succeed, is on the error index — once, for all operations.

Status	When
`401`	No key, or an invalid, revoked or expired key, or a valid key sent to the other environment. `error.type` tells them apart: `authentication_required`, `invalid_api_key`, `api_key_revoked`, `api_key_expired`, `wrong_environment`. On `wrong_environment` the key is fine and the base URL is not — a `vcb_live_…` key was sent to the sandbox host or a `vcb_test_…` key to the live host; `error.gatewayEnvironment` names the host, `error.keyEnvironment` the key. Do not rotate the key, change the URL.
`402`	The balance does not cover this operation (`insufficient_funds`), or the account is not active (`account_not_active`). Do NOT retry — the answer only changes once a top-up happens. `error.availableCents` and `error.requiredCents` name the shortfall, `error.currency` the account's currency.
`403`	The key is not allowed to do this. On `insufficient_scope`, `error.missingScope` names the missing scope; on `ip_not_allowed` the request came from an address outside the allowlist.
`409`	The same idempotency key was used with a different body (`idempotency_key_reuse`), or a request with this key is still in flight (`idempotency_key_in_progress`). The second case may be retried after a short wait.
`429`	Quota exhausted. `Retry-After` and `error.retryAfter` give the wait in seconds. This response MAY be retried — after the stated time.
`500`	A failure on our side. The `requestId` in the response belongs in every support request.
`503`	A supplier is unreachable (`upstream_unavailable`). May be retried, with growing backoff.

Response headers

Set on every response of this operation, successful or not.

Header	Type	Meaning
`X-RateLimit-Limit`	`integer`	Upper limit of the class that applied to this request.
`X-RateLimit-Remaining`	`integer`	Remaining requests in the running window.
`X-RateLimit-Reset`	`integer`	Unix time at which the window starts anew.
`X-Request-Id`	`string (uuid)`	Identifier of this request. Quote it in any support request — including on a successful response, in case the outcome becomes questionable later.

Example

POST /v1/esim/orders

curl -sS -X POST "$VACABEE_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $VACABEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan_01J8…",
  "externalReference": "order-2026-0915-abc",
  "customer": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com"
  }
}'

Set VACABEE_API_URL to https://api.vacabee.com with a live key, or to https://sandbox-api.vacabee.com with a vcb_test_ key. Binding a host to one kind of key is planned and is not enforced by the host yet, so nothing stops a key from being answered at the wrong base URL — assert the prefix against your configured URL yourself. What the sandbox answers

TypeScript SDK

await vacabee.esim.order(…);

The typed method sends the right headers, derives the idempotency key where one is required, and returns the response type generated from this document. Installing and using the SDK