Order lifecycle
Orders move through a set of states identified by integer status codes. The table below describes each state and what it means for your integration.| Code | Name | Description |
|---|---|---|
-1 | Unpaid | Order created but payment not yet confirmed. Cards have not been allocated. |
0 | Normal (paid) | Order paid and active. Cards are allocated and activation codes are available. |
2 | Cancelled | Order cancelled before activation. A refund may have been issued. |
3 | Obsolete / void | Order is void and no longer valid. |
4 | Partial unsubscribe | Some cards in the order have been cancelled; others remain active. |
5 | Ended | All plans on the order have expired or been fully used. |
6 | Unsubscribing in process | A cancellation request has been submitted and is being processed. |
7 | Partial unsubscribe in process | A partial cancellation is being processed for some cards in the order. |
-1 → 0 after payment, then to 5 when all plans expire. Orders that are cancelled move to 2 (fully cancelled) or 4/7 (partially cancelled).
Order structure
The order response contains metadata about the purchase as a whole. Use these fields to display order history, reconcile billing, and determine renewal eligibility.| Field | Type | Description |
|---|---|---|
orderNum | String | Unique order number, e.g. "EP20240124000013". |
display | String | Product display name for the ordered SKU. |
purchaseDate | String | Order creation timestamp (GMT+8). |
count | Integer | Number of SIM cards in the order. |
price | Double | Total cost of the order. |
status | Integer | Current order status code. See Order lifecycle. |
renewal | Boolean | true if this order is a renewal of a previous plan. |
renew | Integer | 0 = this is a main order; 1 = this is a renewal order. |
mainOrderNum | String | The parent order number this renewal is linked to. Present only when renew=1. |
renewOrderNum | Array | List of renewal order numbers associated with this order. |
priceId | Integer | The package price ID that was ordered. |
cardApiDtoList | Array | List of individual card records. See Card details. |
Card details
Each entry incardApiDtoList represents a single SIM card delivered by the order. For eSIM orders, this contains everything needed to activate the plan on a device.
| Field | Type | Description |
|---|---|---|
iccid | String | Unique card identifier. Use this to look up usage and manage the card. |
mobileNumber | String | Phone number assigned to the eSIM. |
sm_dp_address | String | SM-DP+ server address, used to construct the QR code. |
activationCode | String | Activation code for the eSIM profile. |
code | String | Full LPA string for Android activation, formatted as LPA:1$<sm_dp_address>$<activationCode>. |
activateBefore | String | Deadline by which the eSIM must be activated. |
usedMB | Integer | Data consumed so far, in MB. |
startDate | String | Plan start date. |
endDate | String | Plan end date. |
pdfUrl | String | URL to a PDF containing the QR code, ready to send to your customer. |
apn | String | APN setting the customer may need to configure on their device. |
dpId | String | Distribution partner ID. Present on physical SIM orders. |
dpStatus | String | Card status. See Card status values. |
eid | String | eUICC identifier for the device the eSIM is installed on. |
code (LPA string) or pdfUrl to your end user so they can activate the eSIM. On iOS devices, users scan the QR code from the PDF. On Android, users can enter the LPA string directly.
Renewal orders
When a customer’s plan expires and they purchase a continuation, a new renewal order is created and linked to the original order.- The renewal order has
renew=1and amainOrderNumpointing to the original order. - The original order has a
renewOrderNumarray listing all renewal orders placed against it. - The
renewalboolean on the renewal order istrue.
mainOrderNum to trace a renewal back to its origin. Use renewOrderNum on the main order to enumerate all renewals and build a history view for your customers.
Only packages with
flowType=0 (renewable) support renewal orders. Check the package’s flowType before presenting a renewal option. See Renewability.Cancellation and unsubscribe
To cancel an order, call therefundOrder endpoint. The API cancels the order and, where eligible, processes a refund.
Cancellation is subject to the following conditions:
- The plan must not have been activated on a device.
- The plan’s cancellation policy (in the
premarkfield of the package) must permit cancellation. - Some plans are non-refundable after purchase — check
premarkbefore presenting a cancel option.
4 (partial unsubscribe) rather than 2 (fully cancelled). While a cancellation is being processed, the order will show status 6 or 7.
External order IDs
MIOeSIM supports two optional fields for mapping an order to your own platform’s records:| Field | Description |
|---|---|
otherOrderId | Your platform’s order identifier. Pass this when creating an order to tag it with your internal reference. |
otherItemId | Your platform’s line-item identifier for a specific card within the order. |
POST /api_esim/addEsimOrder. They are stored alongside the order and returned in subsequent queries, making it straightforward to reconcile MIOeSIM orders with your own database without maintaining a separate mapping table.