Submit top-up order

To submit a top-up order:

Make a POST request to the endpoint URL {{url}}/{{version}}/orders/topups

Include a request body in the form of a FormData object, which contains the following required fields:

package_id: The ID of the top-up package you want to purchase

iccid: The ICCID of the eSIM for which you want to purchase the top-up package.

You can also include an optional description field to provide additional information about the order.

The API will respond with a JSON object containing the details of the order, including the package ID, quantity, price, and other information.

The complete workflow for buying a top-up package:

GET {{url}}/{{version}}/sims to see the list of purchased eSIMs

GET {{url}}/{{version}}/sims/:iccid/topups to see the list of available top-ups for the eSIMs

POST {{url}}/{{version}}/orders/topups with the proper "iccid" and "package_id" values to purchase a top-up

GET {{url}}/{{version}}/sims/:iccid/packages to see the list of all packages for the eSIM, including the original package and top-ups

Responses

🟢200OK

application/json

Bodyapplication/json

🟢200Submit Top-up Order: 200 OK

🟠400Validation Failed

🟠404eSIM Not Found

🟠422Submit Top-up Order: 422 (Purchase limit exceeded)

🟠422Submit Top-up Order: 422 (Required fields are missing)

🟠422Submit Top-up Order: 422 (Invalid package id)

🟠422Submit Top-up Order: 422 (Recycled sim)

curl --location 'https://prod.your-api-server.com/customer/v2/orders/topups' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' \ --header 'Idempotency-Key;' \ --header 'Content-Type: application/json' \ --data '{ "package_id": "bonbon-mobile-30days-3gb-topup", "iccid": "89340000000000872", "description": "Cuppedia utor eum tergum bene universe conservo corroboro aperte..." }'

{ "success": true, "code": "TOPUP_ORDER_CREATED", "message": "Top-up order created successfully", "data": { "data": { "package_id": "5e0db", "quantity": "1", "type": "sim", "description": "Top-up for customer John Doe", "esim_type": "data", "validity": 7, "package": "Merhaba Top-up - 1GB", "data": "1 GB", "price": 3.5, "created_at": "2024-01-15T10:30:00Z", "id": 12345, "code": "ORD-12345", "currency": "USD", "sims": [ { "id": 1, "iccid": "89012345678901234567" } ] } }, "timestamp": "2025-10-29T12:30:00.000Z" }

Request

Responses