Submit top-up order

post

https://api.esimply.io/v3/orders/submit-topup

Completes an eSIM top-up in a single request.

Validates the iccid, checks your partner wallet balance, provisions the additional data with the upstream carrier, and creates an order record.

Billing Notice: Your prepaid balance is deducted immediately upon success, same as a new eSIM purchase.

Flow: GET /orders/available-topups/{iccid} then POST /orders/submit-topup.

Idempotency (recommended): Send an Idempotency-Key header (e.g. a UUID generated once per top-up attempt). If the request times out, retry with the same key and body — the API returns 200 OK with the original orderID and purchases without performing the top-up or debiting the wallet again.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

iccid

string

required

ICCID of the existing eSIM to top up.

package_id

string

required

package_id from GET /orders/available-topups/{iccid}.

external_package_id

string

required

external_package_id from the same available-topups response row.

end_user_email

string

required

Email address of the end user receiving the top-up.

end_user_phone

string

required

Phone number of the end user in E.164 format.

end_user_first_name

string

required

end_user_last_name

string

required

client_reference

string

Optional partner-defined reference for this order (e.g. your internal user or booking ID).
Stored with the order and filterable via GET /profile/orders?client_reference=....

Headers

Idempotency-Key

string

A unique identifier for this top-up request (e.g. a UUID) provided by the client.
Used to safely retry requests after network timeouts without accidentally performing the same top-up twice.

Responses

200Top-up successfully processed, or an idempotent replay when the same Idempotency-Key is sent again. The response shape is identical in both cases (orderID + purchases).

400Bad Request — ICCID not found, validation error, or insufficient partner balance.

401Unauthorized — The X-API-Key is missing, invalid, or belongs to a different environment.

409Conflict — the request cannot be processed because the cart state is invalid (e.g. cart already submitted or empty on POST /orders/submit-topup, or an unknown cart_key on submit). Note: a successful retry of POST /orders/submit with the same cart_key returns 200 OK, not 409.

500Internal Server Error — An unexpected issue occurred on our end or with the upstream telecom carrier.