Idempotency

A network error can leave you unsure whether a purchase went through. Send an Idempotency-Key header and you can retry without paying twice.

curl -X POST https://api.roamex.com/v1/esims/purchase \
  -H "Authorization: Bearer rmx_your_api_key" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"planId": "your-plan-id", "quantity": 1}'

Use one key per order in your own system, for example your order number. Two endpoints read it: purchase and top-up.

Purchase

A retry counts as the same order when the key, the plan, the quantity, the cost centre and, for a day pass, the days are all the same. Change one of them and it is a new order, charged again, even with the same key.

Result of the first request	Answer to the retry
eSIMs were delivered	`200` with the same eSIMs and `"idempotent_replay": true`. Nothing is charged again.
Still being processed	`409 ORDER_IN_PROGRESS`. Do not retry. Wait for the `order.created` event, or find the eSIMs with List eSIMs.
Ended without an eSIM	`409 ORDER_TERMINAL`. The message says whether the charge was refunded. If it says no refund was recorded, contact support before you try again.

Top-up

The key belongs to your account, the eSIM and the top-up package. A retry with the same key never tops up twice:

Result of the first request	Answer to the retry
Top-up done	`409 DUPLICATE_REQUEST`
Still being processed	`409 ORDER_IN_PROGRESS`. Do not retry. Wait for the `esim.topped_up` event.
Failed	`409 ORDER_TERMINAL`

Without a key

Without a key, an identical request is caught while the first one is still being processed, up to about 10 minutes. After it finished, a purchase is only caught in the same clock minute and a top-up within 60 seconds. After that, the same request buys again.