---
title: "Submit an eSIMply top-up"
method: POST
path: "/esimply/orders/submit-topup"
tags: ["eSIMply orders"]
---

# Submit an eSIMply top-up

`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`

## 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

## Headers

- `Currency` string
- `Idempotency-Key` string, uuid, required

## Request body

- TopUpSubmitRequest
  - `iccid` string, required
  - `packageId` string, required: Package ID as string (provider contract)
  - `externalPackageId` string, required
  - `endUserEmail` string, email, required
  - `endUserPhone` string, required
  - `endUserFirstName` string, required
  - `endUserLastName` string, required
  - `clientReference` string

## Response `200`

Top-up submitted successfully

- object
  - `data` OrderSubmitResponse, required
    - `orderId` string: Public eSIMply order identifier. orders use the provider format (e.g. ord_ plus 16 hex chars). Historical rows may be numeric strings.
    - `purchases` OrderRecord[]
      - `esimId` integer
      - `packageName` string
      - `dataSizeMb` integer
      - `remainingData` integer
      - `destinationCode` string
      - `destinationName` string
      - `price` number
      - `b2bPrice` number
      - `currency` string
      - `iccid` string
      - `qrCode` string: LPA QR string for eSIM installation
      - `smdpAddress` string
      - `activationCode` string
      - `esimProviderId` integer
      - `externalPackageId` string
      - `validityDays` integer
      - `flag` string
      - `createdAt` string, date-time
      - `startDate` string, date-time
      - `endDate` string, date-time
      - `packageId` integer
      - `status` 'active' | 'expired': eSIM plan status: expired when remaining data is 0 or the end date has passed, otherwise active. Returned on order history (`GET /esimply/orders` and `GET /esimply/orders/{iccid}`); omitted from submit and top-up purchase records.

## Other responses

- `400`: Validation error
- `401`: Authentication required
- `403`: eSIMply access not enabled for this account
- `404`: Order not found for ICCID

---

[API](https://skmtc.dev/liteapi/apis/api-esimply.md) - [All operations](https://skmtc.dev/liteapi/apis/api-esimply/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-esimply/revisions/b0fb431f4daf?raw)