eSIM API - Vouchers

Table of Contents

• How Vouchers Work
• Access Requirements
• Create Vouchers
• Get Vouchers
• Get Voucher
• Get Voucher by Code
• Revoke Voucher
• The Voucher Object
• Voucher Statuses

How Vouchers Work

A voucher is a redeemable code that hands one eSIM to whoever holds it. Unlike Orders, a voucher is not tied to a traveller at creation time — you mint a batch, distribute the codes however you like (gift cards, campaigns, hotel check-in, support goodwill), and the eSIM is claimed later by the person who redeems it.

Every voucher is backed by a real eSIM bundle that is created up front, so a batch is capped and is not free to mint. The voucher carries a code and a redeemUrl of the form https://www.getroamify.com/voucher/{code}. Give your customer either one — the code alone if they will type it, the URL if you are sending a link.

Access Requirements

Two separate checks run on every voucher request, both driven by your API key:

The allow-list is an allowlist, not a filter: a key with no configured packages can mint nothing. The packages your key is allowed to use are agreed with Roamify when the feature is switched on — the API does not expose the list, so keep it on your side alongside your key.

Create Vouchers

To mint a batch of vouchers, you need to send a POST request to the /api/esim/vouchers endpoint.

You are required to provide the following parameters in the request body:

• packageId: The ID of the eSIM package to mint vouchers for. This is a required field of type string. It must be one of the packages your API key is allowed to mint.
• quantity: How many vouchers to mint. This is an optional field of type number. It must be a whole number between 1 and 10. The default value is 1.
• referenceId: Your own identifier for this batch. This is an optional field of type string. It must not have been used for a previous batch.
• notes: A free-text note stored on every voucher in the batch. This is an optional field of type string, and may be an empty string.

Usage - create a batch of vouchers

Here is an example of how you can create vouchers using Roamify eSIM API.

curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/vouchers' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "packageId": "esim-global-one-year-365days-0gb-all",
    "quantity": 2,
    "referenceId": "campaign-2026-03",
    "notes": "Spring campaign giveaway"
}'

const axios = require('axios');
 
axios.post('https://api-dev.getroamify.com/api/esim/vouchers', {
    packageId: 'esim-global-one-year-365days-0gb-all',
    quantity: 2,
    referenceId: 'campaign-2026-03',
    notes: 'Spring campaign giveaway'
}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

A successful request returns 201 Created.

{
	"status": "success",
	"data": {
		"referenceId": "campaign-2026-03",
		"requestedQuantity": 2,
		"quantity": 2,
		"vouchers": [
			{
				"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
				"code": "R7K2M9QX4B1D",
				"redeemUrl": "https://www.getroamify.com/voucher/R7K2M9QX4B1D",
				"status": "ACTIVE",
				"referenceId": "campaign-2026-03",
				"packageId": "esim-global-one-year-365days-0gb-all",
				"package": "1 GB - 365 Days",
				"destination": "Global",
				"price": 9,
				"currency": "USD",
				"esimId": "f72d9b90-52b3-47d9-95f6-2cf61ab176aa",
				"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
				"notes": "Spring campaign giveaway",
				"redeemedAt": null,
				"createdAt": 1731837535,
				"updatedAt": 1731837535
			},
			{
				"id": "3f9c1d42-6a77-4a0e-9d19-9d4c1c2f77ab",
				"code": "T4W8ZP2N6C5H",
				"redeemUrl": "https://www.getroamify.com/voucher/T4W8ZP2N6C5H",
				"status": "ACTIVE",
				"referenceId": "campaign-2026-03",
				"packageId": "esim-global-one-year-365days-0gb-all",
				"package": "1 GB - 365 Days",
				"destination": "Global",
				"price": 9,
				"currency": "USD",
				"esimId": "0c1a7b55-9f34-4b62-9a4e-2b7e5d0c9a11",
				"orderId": "a1d2f3c4-5b6e-4f70-8a9b-0c1d2e3f4a5b",
				"notes": "Spring campaign giveaway",
				"redeemedAt": null,
				"createdAt": 1731837535,
				"updatedAt": 1731837535
			}
		]
	}
}

Response fields

• referenceId: The reference ID you sent, or an empty string if you did not send one.
• requestedQuantity: How many vouchers you asked for.
• quantity: How many vouchers were actually created.
• vouchers: The vouchers that were created. See The Voucher Object.

Errors

Get Vouchers

To get a list of your vouchers, you need to send a GET request to the /api/esim/vouchers endpoint.

There are no required parameters for this endpoint, but you can provide the following optional parameters:

• referenceId: Return only the vouchers minted under this reference ID. This is an optional field of type string.
• status: Return only the vouchers in this status. This is an optional field of type string. It must be one of ACTIVE, REDEEMED, or CANCELLED, in uppercase. See Voucher Statuses.
• packageId: Return only the vouchers for this package. This is an optional field of type string.
• limit: The maximum number of vouchers to return. This is an optional field of type number, and must be a whole number of at least 1.

Vouchers are returned newest first, sorted by createdAt descending. limit is applied after sorting, so it returns the most recent N vouchers. Omitting limit returns every matching voucher.

Usage - fetch a list of vouchers

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/vouchers?referenceId=campaign-2026-03&status=ACTIVE&limit=10' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
axios.get('https://api-dev.getroamify.com/api/esim/vouchers', {
    params: {
        referenceId: 'campaign-2026-03',
        status: 'ACTIVE',
        limit: 10
    },
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"referenceId": "campaign-2026-03",
		"vouchers": [
			{
				"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
				"code": "R7K2M9QX4B1D",
				"redeemUrl": "https://www.getroamify.com/voucher/R7K2M9QX4B1D",
				"status": "ACTIVE",
				"referenceId": "campaign-2026-03",
				"packageId": "esim-global-one-year-365days-0gb-all",
				"package": "1 GB - 365 Days",
				"destination": "Global",
				"price": 9,
				"currency": "USD",
				"esimId": "f72d9b90-52b3-47d9-95f6-2cf61ab176aa",
				"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
				"notes": "Spring campaign giveaway",
				"redeemedAt": null,
				"createdAt": 1731837535,
				"updatedAt": 1731837535
			}
		]
	}
}

data.referenceId echoes back the referenceId you filtered on, or an empty string if you did not filter by one.

Errors

Get Voucher

To get a single voucher by its ID, you need to send a GET request to the /api/esim/voucher/{voucherId} endpoint.

You are required to provide the following path parameter:

• voucherId: The ID of the voucher, as returned in the voucher’s id field. This is a required field of type string.

Usage - fetch a voucher by ID

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/voucher/b06036c5-eadc-4f88-aa31-8c207fec91ec' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
const voucherId = 'b06036c5-eadc-4f88-aa31-8c207fec91ec';
 
axios.get(`https://api-dev.getroamify.com/api/esim/voucher/${voucherId}`, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
		"code": "R7K2M9QX4B1D",
		"redeemUrl": "https://www.getroamify.com/voucher/R7K2M9QX4B1D",
		"status": "REDEEMED",
		"referenceId": "campaign-2026-03",
		"packageId": "esim-global-one-year-365days-0gb-all",
		"package": "1 GB - 365 Days",
		"destination": "Global",
		"price": 9,
		"currency": "USD",
		"esimId": "f72d9b90-52b3-47d9-95f6-2cf61ab176aa",
		"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
		"notes": "Spring campaign giveaway",
		"redeemedAt": 1731999000,
		"createdAt": 1731837535,
		"updatedAt": 1731999000
	}
}

Errors

Get Voucher by Code

To look a voucher up by the code you handed out, you need to send a GET request to the /api/esim/voucher/code/{code} endpoint. This is the endpoint to call when a customer contacts you holding only a code.

You are required to provide the following path parameter:

• code: The voucher code. This is a required field of type string.

The code is normalised before it is matched: it is trimmed, upper-cased, and every character that is not a letter or digit is stripped. So r7k2-m9qx-4b1d and R7K2M9QX4B1D both resolve to the same voucher. After normalisation the code must be exactly 12 alphanumeric characters — anything else is reported as 404.

Usage - fetch a voucher by code

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/voucher/code/R7K2M9QX4B1D' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
const code = 'R7K2M9QX4B1D';
 
axios.get(`https://api-dev.getroamify.com/api/esim/voucher/code/${code}`, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
		"code": "R7K2M9QX4B1D",
		"redeemUrl": "https://www.getroamify.com/voucher/R7K2M9QX4B1D",
		"status": "ACTIVE",
		"referenceId": "campaign-2026-03",
		"packageId": "esim-global-one-year-365days-0gb-all",
		"package": "1 GB - 365 Days",
		"destination": "Global",
		"price": 9,
		"currency": "USD",
		"esimId": "f72d9b90-52b3-47d9-95f6-2cf61ab176aa",
		"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
		"notes": "Spring campaign giveaway",
		"redeemedAt": null,
		"createdAt": 1731837535,
		"updatedAt": 1731837535
	}
}

Errors

Revoke Voucher

To cancel a voucher and the eSIM behind it, you need to send a PUT request to the /api/esim/voucher/{voucherId}/revoke endpoint. Use it for a code that was distributed by mistake, leaked, or is no longer wanted.

You are required to provide the following path parameter:

• voucherId: The ID of the voucher to revoke. This is a required field of type string.

No request body is required.

Usage - revoke a voucher

curl --request PUT \
--url 'https://api-dev.getroamify.com/api/esim/voucher/b06036c5-eadc-4f88-aa31-8c207fec91ec/revoke' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
const voucherId = 'b06036c5-eadc-4f88-aa31-8c207fec91ec';
 
axios.put(`https://api-dev.getroamify.com/api/esim/voucher/${voucherId}/revoke`, {}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
		"status": "CANCELLED"
	}
}

Errors

The Voucher Object

Every voucher endpoint returns the same voucher shape.

Voucher Statuses

A voucher’s status can be any of the following values: