Skip to main content
An order in the MIOeSIM system represents a purchase of one or more SIM cards for a given plan. Each order has a unique order number, a lifecycle tracked via status codes, and a list of card records containing the activation details your customers need. Understanding the order structure lets you correctly handle fulfillment, renewals, cancellations, and reconciliation with your own platform.

​
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. In a typical flow, an order transitions from -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.

​
Card details

Each entry in cardApiDtoList represents a single SIM card delivered by the order. For eSIM orders, this contains everything needed to activate the plan on a device. Deliver the 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=1 and a mainOrderNum pointing to the original order.
  • The original order has a renewOrderNum array listing all renewal orders placed against it.
  • The renewal boolean on the renewal order is true.
Use 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 the refundOrder 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 premark field of the package) must permit cancellation.
  • Some plans are non-refundable after purchase — check premark before presenting a cancel option.
When you cancel only some cards in a multi-card order, the order moves to status 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: Pass these when calling 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.