Future orders

POST

/v2/future-orders

This endpoint allows you to submit an order to the Airalo Partner API, which will be created on the specified due date.

To proceed, provide the required information:

Due date

Quantity

Package ID

Description (optional)

Please note:

On success, the endpoint response will include a unique 25-character request_id.

You must store this value in your system to cancel the order later if needed and to know for which order you got a response on your webhook URL.

An access token from the "Request Access Token" endpoint is required in the request.

Delivery modes
What is a webhook URL?
Webhook URL is a URL that is configured on your domain and your won webserver.
That URL should be able to receive HTTP POST requests with your order data that will be sent from our servers .
NOTE: We check the liveness of your webhook URL with an HTTP HEAD request to which we expect 200 OK response.

What happens when the due date arrives?
When the due date arrives your order is processed and the order details are sent as a POST HTTP request to
either your opted in "async_orders" notification type url (more info here )
or on the "webhhok_url" optional parameter of this endpoint which overrides the above opted in URL.
NOTE that you must have one of the above (either opted in URL or webhhok_url) provided in order to make a future order.

if you provide the optional parameter "sharing_option", which goes together with the "to_email" parameter
then an email with the eSim details will also be sent to the email provided in the "to_email" parameter as well.
Depending from the selected sharing option which can be one of link or pdf or both you will get the eSim data
either in a PDF format attached to the email or as a link.

What is the format of the message that is sent to the webhook URL?
The format of the message that is sent to the webhook URL is the same as the response of the regular order.
It only has one additional parameter named "request_id" which is the same request_id that you got in the response
when you made the future order at the time of making the order,
so that you know for which future order you got details on your webhook URL.

For more details and best practices, visit our FAQ page.

Request Example

Shell

JavaScript

Java

Swift

cURL

Request with "webhook_url"Request with all parametersRequest with "sharing_option"

curl --location --request POST '/v2/future-orders' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "quantity": 1,
    "package_id": "change-7days-1gb",
    "due_date": "2025-04-09 10:00",
    "description": "Just a future order ..",
    "webhook_url": "http://somePartnerDomain.com/webhook-url-path-to-wait-for-the order-details"
}'

Response Example

200 - Submit Future Order (200)

{
    "data": {
        "request_id": "9HrK4-KGgz8n71eGgdNS5cV7Y",
        "due_date": "2025-03-28 10:00",
        "latest_cancellation_date": "2025-03-27 10:00"
    },
    "meta": {
        "message": "success"
    }
}

Request

Header Params

string

required

Example:

application/json

Authorization

string

required

Example:

Bearer {ACCESS_TOKEN}

Body Params application/json

quantity

integer

required

The quantity of items in the order. Maximum of 50.

>= 1<= 50

package_id

string

required

Required. The package ID associated with the order. You can obtain this from the "Packages / Get Packages" endpoint.

Example:

kallur-digital-7days-1gb

due_date

string <date-time>

required

Required. Date and time string field in the format YYYY-MM-DD HH:MM. This date must be minimum two days in the future from current time and maximum 1 year in the future. The order processing starts at the moment the due date arrives.

Example:

2025-03-28 10:00

to_email

string

optional

If specified, email with esim sharing will be sent. sharing_option should be specified as well.

Example:

valid_email@address.com

sharing_option

array[string]

optional

Array. Required when to_email is set. Available options: link, pdf

Allowed values:

linkpdf

copy_address

string

optional

Array. It is used when to_email is set.

Example:

["valid_email@address.com"]

webhook_url

string

optional

Optional. A custom, valid url to which you will receive the order details data asynchronously. Note that you can optin or provide in request. The webhook_url if provided in payload will overwrite the one which is opted in.

description

string

optional

Optional. A custom description for the order, which can help you identify it later.

brand_settings_name

string | null

optional

Nullable. The definition under what brand the eSIM should be shared. Null for unbranded.

Example:

our perfect brand

Examples

Responses

🟢200Submit Future Order

application/json

Body

data

object

required

request_id

string

required

A unique string from 25 charachers for your submitted order that you can use it later to make other operations on the order. For example to cancel it if needed.

due_date

string

required

The submitted due date with the order

latest_cancellation_date

string

required

Latest cancelation date