> ## Documentation Index > Fetch the complete documentation index at: https://developers.mioesim.com/llms.txt > Use this file to discover all available pages before exploring further. # Orders: the MIOeSIM order lifecycle > Learn how MIOeSIM orders are structured, what each status code means, how renewal and cancellation work, and how to map orders to your platform's IDs. 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. | 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. | 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. | 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](#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). | ## 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. | 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$$`. | | `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](/concepts/iccid-and-cards#card-status-values). | | `eid` | String | eUICC identifier for the device the eSIM is installed on. | 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](/concepts/skus-and-packages#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: | 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. | 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.