LIliteapi
eSIMply orders

Submit an eSIMply top-up

Overview

Apply a top-up package to an existing eSIM in a single request. On success you receive an order response with updated purchase details. Successful top-ups are persisted for the partner account.

When to Use

  • Add more data - Traveler needs additional MB on an existing eSIM
  • Extend connectivity - Apply a package without issuing a new ICCID
  • Safe retries - Resubmit with the same Idempotency-Key after network failures

What You Get

  • Order ID - Provider order identifier for the top-up
  • Purchase details - Updated package, pricing, and eSIM identifiers

Key Features

  • Idempotency: Required Idempotency-Key header for safe retries
  • Currency conversion: Optional Currency header for priced fields
  • Persistent records: Successful top-ups are stored in liteAPI
post/esimply/orders/submit-topup

Request

  • Base URL
    https://api.liteapi.travel/v3.0
  • URL
    https://api.liteapi.travel/v3.0/esimply/orders/submit-topup
  • Auth
    API key in header X-API-Key

Headers

Currencystring
Example:EUR

Optional ISO-4217 currency code. When set, priced fields are converted using liteAPI exchange rates only (not forwarded to eSIMply).

Idempotency-Keystring uuid required
Example:550e8400-e29b-41d4-a716-446655440000

Required UUID idempotency key for safe retries of top-up submit.

Request body

iccidstring required
packageIdstring required

Package ID as string (provider contract)

externalPackageIdstring required
endUserEmailstring email required
endUserPhonestring required
endUserFirstNamestring required
endUserLastNamestring required
clientReferencestring

Example request

{
  "iccid": "89000000000000000001",
  "packageId": "1",
  "externalPackageId": "choukran-7days-1gb",
  "endUserEmail": "traveler@example.com",
  "endUserPhone": "+14155552671",
  "endUserFirstName": "Jane",
  "endUserLastName": "Doe",
  "clientReference": "demo-topup-001"
}

Response

Top-up submitted successfully

Example response

{
  "data": {
    "orderId": "ord_8a9b2c3d4e5f6789",
    "purchases": [
      {
        "esimId": 10001,
        "packageName": "1 GB",
        "dataSizeMb": 1024,
        "remainingData": 1024,
        "destinationCode": "MA",
        "destinationName": "Morocco",
        "price": 3.46,
        "b2bPrice": 3.46,
        "currency": "EUR",
        "iccid": "89000000000000000001",
        "qrCode": "LPA:1$smdp.example.com$EXAMPLEACTIVATIONCODE0001",
        "smdpAddress": "smdp.example.com",
        "activationCode": "EXAMPLEACTIVATIONCODE0001",
        "esimProviderId": 4,
        "externalPackageId": "MA|1024",
        "validityDays": 7,
        "flag": "https://esimply-destinations-flags.s3.us-west-1.amazonaws.com/ma.svg",
        "createdAt": "2026-08-12T16:12:49Z",
        "startDate": "2026-08-20T00:00:00Z",
        "endDate": "2026-08-27T00:00:00Z",
        "packageId": 1
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.