eSIM code examples

This page is about travel eSIMs. Selling gift cards instead? See Gift card code examples.

curl, PHP, Node.js and Python.

Each example reads the key from the NOVACODES_KEY environment variable and uses nothing beyond the language's usual HTTP client. The later examples reuse what the ordering example defines: the buy function in every language, and API and HEADERS in Node.js and Python.

List the plans of a destination

curl -s https://api.novacodes.app/v1/esim/destinations/MV \
  -H "Authorization: Bearer $NOVACODES_KEY"

Order with a reference, retry-safe

The function retries timeouts, 429 and 5xx with the same reference, and stops on a refusal such as insufficient_balance. Its timeout of 45 seconds leaves room for the order call, which can take about 20 seconds.

curl -s https://api.novacodes.app/v1/esim/orders \
  -H "Authorization: Bearer $NOVACODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":43,"quantity":1,"balance":"MVR","reference":"trip-8841"}'

Generate the reference from something you already store, such as your booking or order id, before the first attempt. A random value made inside the retry loop would defeat the protection.

Poll until the order is no longer processing

Most orders answer completed at once. When the status is processing, read the order every few seconds until it changes. An empty esims list on a refunded order means the purchase was refused and your money is back.

curl -s https://api.novacodes.app/v1/esim/orders/trip-8841 \
  -H "Authorization: Bearer $NOVACODES_KEY"

Top up an eSIM

Ask what can be added to the eSIM, then buy one of those plans with the same buy function and a new reference.

# 1. What can be added to this eSIM
curl -s https://api.novacodes.app/v1/esim/esims/8985224628000101/topups \
  -H "Authorization: Bearer $NOVACODES_KEY"

# 2. Add one of those plans, with a reference of its own
curl -s https://api.novacodes.app/v1/esim/esims/8985224628000101/topups \
  -H "Authorization: Bearer $NOVACODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":45,"balance":"MVR","reference":"trip-8841-more"}'

Cancel an eSIM for a refund

Only an eSIM that was never installed and never topped up can be cancelled. A refusal is an ordinary answer, not a failure of your code: show the message.

curl -s -X POST https://api.novacodes.app/v1/esim/esims/8985224628000102/cancel \
  -H "Authorization: Bearer $NOVACODES_KEY"