Top-up Journey
Data eSIM Service - Top-up Journey
| Top-up Packages | Top-up Order | Package History | Orders List |
|---|---|---|---|
| User journey: Choose from a range of top-up packages | User journey: Proceed to checkout and place a top-up order | User journey: View ordered packages for a given eSIM | User journey: View past orders independently from eSIM |
| Endpoint: GET /customer/v2/sims/:iccid/topups | Endpoint: POST /customer/v2/orders/topups | Endpoint: GET /customer/v2/sims/:iccid/packages | Endpoint: GET /customer/v2/orders |
Description: [Get Top-up Packages] provides list of top-up packages for a given eSIM. It is important to query available packages for the eSIM all the time before submitting Top-up order, cannot use any cached data from earlier request. Top-up is only available for an active eSIM only. Get Packages v2 returns with all available Top-up packages optionally using include=topup parameter. | Description: [Submit Top-up Order] creates a top-up order for an existing eSIM to add more data, voice minutes, or SMS. First step is always to get the available Top-up packages for an eSIM. Available top-up packages can change, even for the same eSIM at different times. Important note: Make a top-up order only after payment is collected from the end user. Ensure your account has sufficient balance (pre-paid) or available credit (post-paid) before placing orders. | Description: [Get Package History] provides a list of packages ordered for a given eSIM, including the original package and all top-ups. Limitation: Make sure to cache the result for up to 15 minutes for the same eSIM. The endpoint allows 1 request for an eSIM per 15 minutes to prevent rate limiting. | Description: [Get Order List] provides an overview of orders including top-up orders independently from an eSIM. Tip: If the partner used the "description" field during the submit process, it can be used for filtering. |
| Response: List of top-up packages available for the eSIM: - id: Top-up package id - the one must be used in submit top-up order- price: PressOne retail price- net_price: Package net price (wholesale price)- amount: Data amount in megabytes- day: Validity in days- title: Package title- voice: Voice minutes (if included)- text: SMS messages (if included)- data: Data amount description | Response: - package_id: Top-up package id- order_id: Order id- code: Order code- iccid: eSIM ICCID- package: Package name and description- data: Data amount- validity: Validity period- price: Order price- created_at: Order creation timestamp- sims: Array of SIM details included in the top-up | Response: Package details: List of Order details including: - package_id: Package id- status: "ACTIVE", "EXPIRED", "FINISHED", etc.- remaining: Remaining data in megabytes- remaining_voice: Remaining voice minutes- remaining_text: Remaining number of text messages- activated_at: Timestamp of activation (e.g., "2023-01-09T10:30:45+00:00")- expired_at: Expiry date in case the package was already activated (timestamp)- finished_at: Timestamp of date when the data was used- data: Total data amount- validity: Validity period | Response: Driven on the "include" request parameter it can return the list of brief order details plus: a. eSIM details b. User details c. Status Each order includes: - id: Order id- code: Order code- package_id: Package id- type: Order type (sim, topup)- status: Order status- created_at: Order creation timestamp- description: Order description |
| Request: - iccid: Unique id for the eSIM returned by [Submit Order] or [Get eSIM List] (Path variable) | Request: - package_id: Top-up package id returned by [Get Top-up Packages]. Cannot use eSIM (local, regional, global) packages! Top-up packages are ALWAYS related to eSIM and ids are different- iccid: Unique id for the eSIM returned by [Submit Order] or [Get eSIM List] (Path variable)- description: Optional but can be used for filtering orders in [Get Order List]Tip: Use customer id, or customer id and own order id combination | Request: - iccid: Unique id for the eSIM returned by [Submit Order] or [Get eSIM List] (Path variable)Tip: Implement client-side caching to handle frequent customer requests and avoid rate limit errors. | Request: - include: Optional. A comma-separated string to include related data in the response. Possible values are "sims", "user", and "status"- Filtering: By created_at, code (order code), order_status, iccid- description: As a tip, can be anything that was given as description during the order submit, like customer id- type: Filter by order type (sim, topup)- page and limit: Pagination parameters |
Voice-Only eSIM Service - Renewal Journey
| Renewal |
|---|
| User journey: Renew subscription or convert free trial to paid |
| Endpoint: POST /api/third-party/partner/renew-number/ |
| Description: [Renew Number] triggers renewal for a user and also to switch them from free trial to paying. Use this endpoint when a subscription needs to be renewed or when converting a free trial user to a paid subscription. |
| Response: - message: Success or error message- success: Boolean indicating if the operation was successful- data: Response data (null on success) |
| Request: - email: User's email address (required) - used to identify the userTip: Monitor subscription status through the List User endpoint and proactively renew subscriptions before they expire to ensure continuous service for your users. |
Modified at 2025-11-15 22:26:25