Skip to Content
🚀 Trusted by travel businesses worldwide - Roamify eSIM API
eSIMs ModuleOrders

eSIM API - Orders

Table of Contents

Create eSIM Order

To create an eSIM order, you need to send a POST request to the /api/esim/order endpoint.

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

  • items: An array of eSIM items you want to order. Each item should contain the following details:
    • packageId: The ID of the eSIM package you want to order. This is a required field of type string.
    • quantity: The quantity of the eSIM package you want to order. This is a required field of type number.
  • referenceId: The reference ID for the order. This is an optional field of type string. (Your custom reference ID for the order, if needed.)

Usage - create an eSIM order

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

curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/order' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json' \
--data '{
    "items": [
        {
            "packageId": "Package ID",
            "quantity": 1
        }
    ],
    "referenceId": "Optional Reference ID"
}'

Sample Response

{
	"status": "success",
	"data": {
		"id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
        "referenceId": "ref-123456",
		"orderType": "api",
		"status": "COMPLETED",
		"total": 5,
		"currency": "USD",
		"createdAt": 1731837535,
		"updatedAt": 1731837539,
		"items": [
			{
				"esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
				"packageId": "esim-cambodia-7days-1gb-all",
				"package": "1 GB - 7 Days",
				"type": "esim",
				"price": 5,
				"currency": "USD",
				"createdAt": 1731837535,
				"updatedAt": 1731837539
			}
		]
	}
}

Create Top-up Order

To create a top-up order, you need to send a POST request to the /api/esim/order/topup endpoint.

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

  • iccid: The ICCID of the eSIM you want to top-up. This is a required field of type string.
  • packageId: The ID of the eSIM package you want to top-up. This is a required field of type string.
  • referenceId: The reference ID for the top-up order. This is an optional field of type string. (Your custom reference ID for the order, if needed.)

Usage - create a top-up order

Here is an example of how you can create a top-up order using Roamify eSIM API.

curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/order/topup' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json' \
--data '{
    "iccid": "ICCID",
    "packageId": "Package ID",
    "referenceId": "Optional Reference ID"
}'

Sample Response

{
	"status": "success",
	"data": {
		"id": "0501aef3-7cf1-4b4c-a293-c03a6bd7a8ab",
        "referenceId": "ref-123456",
		"orderType": "api",
		"status": "COMPLETED",
		"total": 5,
		"currency": "USD",
		"createdAt": 1731838277,
		"updatedAt": 1731838280,
		"items": [
			{
				"esimId": "22dcdb84-968b-415c-bb70-79e2f3ffc296",
				"packageId": "esim-cambodia-7days-1gb-all",
				"package": "1 GB - 7 Days",
				"type": "esim",
				"price": 5,
				"currency": "USD",
				"createdAt": 1731838277,
				"updatedAt": 1731838280
			}
		]
	}
}

Create Instant eSIM Order

To create an instant eSIM order, you need to send a POST request to the /api/esim/order/instant endpoint.

⚠️

Please make sure you have timeout set to at least 60 seconds to use this endpoint. Depends on what you order, the fulfillment time can varies

⚠️

There is no need to call /apply endpoint with this endpoint

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

  • items: An array of eSIM items you want to order. Each item should contain the following details:
  • packageId: The ID of the eSIM package you want to order. This is a required field of type string.
  • quantity: The quantity of the eSIM package you want to order. This is a required field of type number.
    • referenceId: The reference ID for the order. This is an optional field of type string. (Your custom reference ID for the order, if needed.)

Usage - create an instant eSIM order

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

curl --request POST \
--url 'https://api-dev.getroamify.com/api/esim/order' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"packageId": "Package ID",
"quantity": 1
}
],
"referenceId": "Optional Reference ID"
}'

Sample Response

{
	"status": "success",
	"data": {
        "id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
        "referenceId": "ref-123456",
        "orderType": "api",
        "status": "COMPLETED",
        "total": 5,
        "currency": "USD",
        "createdAt": 1731837535,
        "updatedAt": 1731837539,
        "esims": [
              {
                "id": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
                "iccid": "894000000000029365",
                "status": "READY",
                "activation": "first-use",
                "withTopUp": true,
                "withHotspot": true,
                "withDataRoaming": true,
                "withDestinationInstall": false,
                "withUsageCheck": true,
                "esim": {
                    "lpaCode": "LPA:1$lpa.roamify.com$TEST",
                    "smdpAddress": "lpa.roamify.com",
                    "activationCode": "TEST",
                    "qrCodeUrl": "https://imagedelivery.net/uUE6LNs_ci8SFBH4_n66dQ/partners/b06036c5-eadc-4f88-aa31-8c207fec91ec/iccid/public",
                    "pin": "",
                    "puk": "",
                    "number": "",
                    "iosQuickInstall": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.roamify.com$TEST",
                    "androidQuickInstall": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$lpa.roamify.com$TEST"
                },
                "apn": {
                    "apnAutomatic": true,
                    "apnName": "",
                    "apnUsername": "",
                    "apnPassword": ""
                },
                "data": {
                    "isUnlimited": false
                },
                "call": {
                    "withCall": false,
                    "callType": "all"
                },
                "sms": {
                    "withSMS": false,
                    "smsType": "all"
                },
                "notes": [],
                "createdAt": 1731837539,
                "updatedAt": 1731837987,
                "expiredAt": 1763373985
              }
        ]
    }
}

Get eSIM Order

To get a specific eSIM order, you need to send a GET request to the /api/esim/order endpoint.

You are required to provide either orderId or referenceId as a query parameter:

  • orderId: The ID of the eSIM order you want to retrieve. This is an optional field of type string.
  • referenceId: The reference ID of the eSIM order you want to retrieve. This is an optional field of type string.

Usage - fetch an eSIM order

Here is an example of how you can get a specific eSIM order using Roamify eSIM API.

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/order?orderId=Order ID' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'

Sample Response

{
	"status": "success",
	"data": {
		"id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
        "referenceId": "ref-123456",
		"orderType": "api",
		"status": "COMPLETED",
		"total": 5,
		"currency": "USD",
		"createdAt": 1731837535,
		"updatedAt": 1731837539,
		"items": [
			{
				"esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
				"packageId": "esim-cambodia-7days-1gb-all",
				"package": "1 GB - 7 Days",
				"type": "esim",
				"price": 5,
				"currency": "USD",
				"createdAt": 1731837535,
				"updatedAt": 1731837539
			}
		]
	}
}

Get eSIM Orders

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

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

  • status: The status of the eSIM orders. This is an optional field of type string. It can be any of the following values:

    • PENDING: Pending orders
    • COMPLETED: Completed orders
    • ARCHIVED: Archived orders
    • CANCELLED: Cancelled orders
    • REFUNDED: Refunded orders
    • REQUIRE_ACTION: Orders that require action

  • limit: The number of eSIM orders to return. This is an optional field of type number. The default value is 50.

  • referenceId: The reference ID of the eSIM orders you want to retrieve. This is an optional field of type string.

Usage - fetch a list of eSIM orders

Here is an example of how you can get a list of eSIM orders using Roamify eSIM API.

curl --request GET \
--url 'https://api-dev.getroamify.com/api/esim/orders?status=PENDING&limit=10' \
--header 'Authorization: Bearer Access Token' \
--header 'Content-Type: application/json'

Sample Response

{
	"status": "success",
	"data": {
		"orders": [
			{
				"id": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
                "referenceId": "ref-123456",
				"orderType": "api",
				"status": "COMPLETED",
				"total": 5,
				"currency": "USD",
				"createdAt": 1731837535,
				"updatedAt": 1731837539,
				"items": [
					{
						"esimId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
						"packageId": "esim-cambodia-7days-1gb-all",
						"package": "1 GB - 7 Days",
						"type": "esim",
						"price": 5,
						"currency": "USD",
						"createdAt": 1731837535,
						"updatedAt": 1731837539
					}
				]
			}
		]
	}
}
PackageseSIMs