Create eSIM order
Create a new eSIM order — requires a read+write API key.
POST /api/v1/esims/orders
Permission: Read+Write
Creates a new eSIM, debits your agency balance, and provisions it with the supplier. Pricing is always computed server-side — see eSIM pricing.
Request
curl --request POST \
--url https://api.fx-port.com/api/v1/esims/orders \
--header 'Authorization: Bearer fxp_test_YOUR_KEY' \
--header 'Content-Type: application/json' \
--data '{
"package_id": "elan-7days-1gb",
"first_name": "Ana",
"last_name": "Kova",
"email": "[email protected]",
"phone": "+34600123456",
"description": "Order for Ana Kova"
}'Body fields
Verified directly against the running API — sending a request without email or without phone
returns 400.
| Field | Required | Description |
|---|---|---|
package_id | Yes | id from the package catalog |
email | Yes | Traveler/client email. The supplier emails the QR code and installation instructions directly to this address |
phone | Yes | Traveler/client phone number |
first_name / last_name | No | Traveler name — plain Latin/ASCII letters only |
description | No | Free-text order note |
There is no quantity field. Every order creates exactly one eSIM — pricing and the agency
balance debit only ever account for a single eSIM. If a client sends quantity anyway, it is
silently ignored; to get more eSIMs, call this endpoint once per eSIM.
Only pass the traveler's/client's own email and phone number — never billing, pricing, or account
information. email and phone are forwarded to the supplier purely as customer-facing contact
details for eSIM delivery and installation help.
Response example
{
"success": true,
"data": {
"order": {
"code": "20260827-088478",
"package_id": "elan-7days-1gb",
"type": "sim",
"description": "Order for Ana Kova",
"validity": 7,
"price": 9.52,
"currency": "EUR",
"net_price": 8.50,
"total_price": 9.52,
"agency_currency": "EUR",
"supplier_currency": "USD",
"exchange_rate": 0.92,
"coverage": "France"
},
"sim": {
"iccid": "8900000338153738419",
"qrcode_url": "https://...",
"direct_apple_installation_url": "https://...",
"apn_type": "automatic",
"apn_value": "N/A",
"sharing": {
"access_code": 8803,
"link": "https://esims.cloud/example-share-link"
}
}
},
"booking_id": "FX-1787835379756",
"message": "eSIM order placed successfully"
}Save sim.iccid — it's required for topups, usage, and
installation instructions. Save booking_id for booking lookups.
Errors
| HTTP | Cause |
|---|---|
400 | package_id missing, or email/phone missing/invalid |
402 | Insufficient agency balance |
403 | Key lacks write permission, or agency is not active |
404 | Package not found or has no valid price |
409 | Duplicate order already in flight for this agency/package |
503 | Supplier temporarily unavailable |
In the sandbox environment, orders never debit a balance and no real eSIM is provisioned —
the response includes "balanceDebited": false.