> For the complete documentation index, see [llms.txt](https://docs.esimpay.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.esimpay.net/eng/api/orders.md).
# Orders
Full order lifecycle and connectivity status.
Creating, topping up, activating, refunding, and tracking eSIM orders.
## Activate an ON\_DEMAND package
> \
> Activates a data package purchased with \`activationMode=ON\_DEMAND\`. \
> Requires the \`CF-MERCHANT-ID\` and \`CF-ACCESS-SIGN\` headers.\
> \
> \---\
> \
> \*\*Requirements:\*\*\
> \- The package's \`activationMode\` must be \`ON\_DEMAND\`\
> \- The package must not already be activated (\`activatedAt = null\`)\
> \
> \---\
> \
> \*\*Signature:\*\* obtain it via \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/activate":{"post":{"operationId":"activate_order","summary":"Activate an ON_DEMAND package","description":"\nActivates a data package purchased with `activationMode=ON_DEMAND`. \nRequires the `CF-MERCHANT-ID` and `CF-ACCESS-SIGN` headers.\n\n---\n\n**Requirements:**\n- The package's `activationMode` must be `ON_DEMAND`\n- The package must not already be activated (`activatedAt = null`)\n\n---\n\n**Signature:** obtain it via `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 signature of the request body","required":true}],"responses":{"200":{"description":"Package activated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"idPack":{"type":"integer"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid parameters, package not found, or already activated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["idPack"],"type":"object","properties":{"idPack":{"description":"Package ID obtained when the package was created","type":"integer"}}}}},"required":true}}}}}
```
## Get eSIM profile connectivity information
> \
> Returns connectivity information for an eSIM profile by ICCID. \
> Requires the \`CF-MERCHANT-ID\` and \`CF-ACCESS-SIGN\` headers.\
> \
> \---\
> \
> \*\*Signature:\*\* for GET requests, pass an empty object \`{}\` as the \`payload\` field in \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/connectivity":{"get":{"operationId":"connectivity_order","summary":"Get eSIM profile connectivity information","description":"\nReturns connectivity information for an eSIM profile by ICCID. \nRequires the `CF-MERCHANT-ID` and `CF-ACCESS-SIGN` headers.\n\n---\n\n**Signature:** for GET requests, pass an empty object `{}` as the `payload` field in `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 request signature","required":true},{"schema":{"type":"string"},"name":"iccid","in":"query","description":"eSIM profile ICCID","required":true}],"responses":{"200":{"description":"Connectivity information retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"connectivity":{"type":"object","properties":{"active":{"type":"boolean"},"eid":{"type":"string"},"iccid":{"type":"string"},"imsi":{"type":"string"},"lastCountryCodeChange":{"type":"string"},"lastDataConsumed":{"type":"string"},"lastNetwork":{"type":"string"},"lastTimeConnected":{"type":"string"},"state":{"type":"string"}}}}}}}},"400":{"description":"Invalid parameters or eSIM profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"]}}}}
```
## Get order status
> \
> Returns the current order status by \`uidCustomer\`.\
> \
> \---\
> \
> \*\*Order \`status\` values:\*\*\
> \
> \| Value | Description |\
> \|-------|-------------|\
> \| \`in\_processing\` | Order is being processed — eSIM not issued yet |\
> \| \`completed\` | eSIM issued — a full data object is returned |\
> \| \`canceled\` | Order canceled — funds returned to balance |\
> \
> For \`completed\` — a full object is returned with \`esimProfile\`, \`customer\`, and a list of \`activatedItems\`. \
> For \`in\_processing\` or \`canceled\` — only basic identifiers are returned.\
> \
> \---\
> \
> \*\*Signature:\*\* for GET requests, pass an empty object \`{}\` as the \`payload\` field in \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/getStatus":{"get":{"operationId":"get_order_status","summary":"Get order status","description":"\nReturns the current order status by `uidCustomer`.\n\n---\n\n**Order `status` values:**\n\n| Value | Description |\n|-------|-------------|\n| `in_processing` | Order is being processed — eSIM not issued yet |\n| `completed` | eSIM issued — a full data object is returned |\n| `canceled` | Order canceled — funds returned to balance |\n\nFor `completed` — a full object is returned with `esimProfile`, `customer`, and a list of `activatedItems`. \nFor `in_processing` or `canceled` — only basic identifiers are returned.\n\n---\n\n**Signature:** for GET requests, pass an empty object `{}` as the `payload` field in `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 signature of the request body","required":true},{"schema":{"type":"string"},"name":"uidCustomer","in":"query","description":"Order UUID obtained at creation","required":true}],"responses":{"200":{"description":"Status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"uidCustomer":{"type":"string"},"orderId":{"type":"string"},"status":{"type":"string","enum":["in_processing","completed","canceled"]},"createdAt":{"type":"string"},"esimProfile":{"description":"Only when status=completed","type":["object","null"],"properties":{"iccid":{"type":"string"},"imsi":{"type":"string"},"activationCode":{"type":"string"},"appleUniversalLink":{"type":["string","null"]},"androidUniversalLink":{"type":["string","null"]},"installationUrl":{"type":["string","null"]},"state":{"type":"string"},"active":{"type":"boolean"},"activatedAt":{"type":["string","null"]}}},"customer":{"description":"Only when status=completed","type":["object","null"],"properties":{"uidCustomer":{"type":"string"},"profileUrl":{"type":["string","null"]}}},"activatedItems":{"description":"List of packages. Only when status=completed","type":["array","null"],"items":{"type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"activationMode":{"type":"string"},"countrySet":{"type":"string"},"salesDate":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"activatedAt":{"type":["string","null"]},"validity":{"type":"object","properties":{"size":{"type":"integer"},"unit":{"type":"string"}}},"availableBalance":{"type":"object","properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}},"size":{"type":"object","properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}},"salePrice":{"type":"number"},"reward":{"description":"Merchant reward in USD","type":["number","null"]},"rewardPercent":{"description":"Reward markup percent","type":["number","null"]},"status":{"type":"string"}}}},"totalAvailableBalance":{"description":"Total remaining balance across all packages","type":["object","null"],"properties":{"sizeUnit":{"type":"string"},"sizeValue":{"type":"integer"}}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"]}}}}
```
## Refund a data package
> \
> Requests a refund for a purchased data package. \
> Requires the \`CF-MERCHANT-ID\` and \`CF-ACCESS-SIGN\` headers.\
> \
> \---\
> \
> \*\*Refund conditions — all must be met:\*\*\
> \
> \| Condition | Description |\
> \|-----------|-------------|\
> \| Package status | Valid (not expired) and unused (full remaining data balance) |\
> \| Activation | Package not yet activated (\`activatedAt = null\`) |\
> \| Monthly limit | The refund limit for the current month has not been reached |\
> \
> If all conditions are met, the package cost is credited back to the merchant's balance. \
> Otherwise, the system returns an error.\
> \
> \---\
> \
> \*\*Signature:\*\* obtain it via \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/refund":{"post":{"operationId":"refund_order","summary":"Refund a data package","description":"\nRequests a refund for a purchased data package. \nRequires the `CF-MERCHANT-ID` and `CF-ACCESS-SIGN` headers.\n\n---\n\n**Refund conditions — all must be met:**\n\n| Condition | Description |\n|-----------|-------------|\n| Package status | Valid (not expired) and unused (full remaining data balance) |\n| Activation | Package not yet activated (`activatedAt = null`) |\n| Monthly limit | The refund limit for the current month has not been reached |\n\nIf all conditions are met, the package cost is credited back to the merchant's balance. \nOtherwise, the system returns an error.\n\n---\n\n**Signature:** obtain it via `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 signature of the request body","required":true}],"responses":{"200":{"description":"Refund completed — funds credited to the merchant balance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"idPack":{"type":"integer"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid parameters, package not found, already activated, or refund conditions not met","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["idPack"],"type":"object","properties":{"idPack":{"description":"Package ID obtained when the package was created","type":"integer"}}}}},"required":true}}}}}
```
## Create order
> \
> Creates a new order to purchase an eSIM package. \
> Requires the \`CF-MERCHANT-ID\` and \`CF-ACCESS-SIGN\` headers. \
> Debits the merchant's balance and triggers eSIM profile issuance.\
> \
> \---\
> \
> \*\*\`activationMode\` parameter:\*\*\
> \
> \| Value | Description |\
> \|-------|-------------|\
> \| \`NOW\` | The package activates immediately after purchase \*(default)\* |\
> \| \`FIRST\_USE\` | The package activates on first network connection |\
> \| \`ON\_DEMAND\` | The package is activated manually via the API |\
> \
> \---\
> \
> \*\*Signature:\*\* obtain it via \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/submit":{"post":{"operationId":"create_order","summary":"Create order","description":"\nCreates a new order to purchase an eSIM package. \nRequires the `CF-MERCHANT-ID` and `CF-ACCESS-SIGN` headers. \nDebits the merchant's balance and triggers eSIM profile issuance.\n\n---\n\n**`activationMode` parameter:**\n\n| Value | Description |\n|-------|-------------|\n| `NOW` | The package activates immediately after purchase *(default)* |\n| `FIRST_USE` | The package activates on first network connection |\n| `ON_DEMAND` | The package is activated manually via the API |\n\n---\n\n**Signature:** obtain it via `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 signature of the request body","required":true}],"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"esimProfile":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"salePrice":{"type":"number"}}},"uidCustomer":{"type":"string"},"orderId":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters or product not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Insufficient funds on the merchant balance","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"An order with this orderId already exists","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"uidCustomer":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["productId"],"type":"object","properties":{"orderId":{"description":"Unique order identifier on the merchant side","type":"string"},"productId":{"description":"Product (package) identifier","type":"string"},"activationMode":{"description":"eSIM activation mode","type":"string","enum":["NOW","FIRST_USE","ON_DEMAND"]},"callback":{"description":"URL for order status webhook notifications","type":["string","null"]}}}}},"required":true}}}}}
```
## Purchase an additional package for an existing eSIM profile
> \
> Creates an additional data package for an existing eSIM profile. \
> Requires the \`CF-MERCHANT-ID\` and \`CF-ACCESS-SIGN\` headers. \
> Debits the merchant's balance and queues the package for activation.\
> \
> \---\
> \
> \*\*\`activationMode\` parameter:\*\*\
> \
> \| Value | Description |\
> \|-------|-------------|\
> \| \`NOW\` | The package activates immediately after purchase \*(default)\* |\
> \| \`FIRST\_USE\` | The package activates on first network connection |\
> \| \`ON\_DEMAND\` | The package is activated manually via the API |\
> \
> \---\
> \
> \*\*Signature:\*\* obtain it via \`POST /customer/sign\`, then copy \`signature\` into the \`CF-ACCESS-SIGN\` header.
```json
{"openapi":"3.1.1","info":{"title":"API","version":"v1"},"tags":[{"name":"Orders","description":"Creating, topping up, activating, refunding, and tracking eSIM orders."}],"servers":[{"url":"https://api.esimpay.net/api/v1"}],"paths":{"/orders/topup":{"post":{"operationId":"top_up_order","summary":"Purchase an additional package for an existing eSIM profile","description":"\nCreates an additional data package for an existing eSIM profile. \nRequires the `CF-MERCHANT-ID` and `CF-ACCESS-SIGN` headers. \nDebits the merchant's balance and queues the package for activation.\n\n---\n\n**`activationMode` parameter:**\n\n| Value | Description |\n|-------|-------------|\n| `NOW` | The package activates immediately after purchase *(default)* |\n| `FIRST_USE` | The package activates on first network connection |\n| `ON_DEMAND` | The package is activated manually via the API |\n\n---\n\n**Signature:** obtain it via `POST /customer/sign`, then copy `signature` into the `CF-ACCESS-SIGN` header.\n","parameters":[{"schema":{"type":"string"},"name":"CF-MERCHANT-ID","in":"header","description":"Merchant identifier for authentication","required":true},{"schema":{"type":"string"},"name":"CF-ACCESS-SIGN","in":"header","description":"HMAC-SHA256 signature of the request body","required":true}],"responses":{"200":{"description":"Package queued for activation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"uidCustomer":{"type":"string"},"package":{"type":"object","properties":{"id":{"type":"integer"},"productId":{"type":"string"},"name":{"type":"string"},"orderId":{"type":["string","null"]},"status":{"type":"string"},"salePrice":{"type":"number"}}}}}}}},"400":{"description":"Invalid request parameters, profile or product not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Insufficient funds on the merchant balance","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"}}}}}},"409":{"description":"An order with this orderId already exists","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"uidCustomer":{"type":"string"}}}}}}},"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"required":["uidCustomer","productId"],"type":"object","properties":{"uidCustomer":{"description":"UUID of the existing eSIM profile","type":"string"},"productId":{"description":"Product (package) identifier","type":"string"},"orderId":{"description":"Unique order identifier on the merchant side","type":"string"},"activationMode":{"description":"Package activation mode","type":"string","enum":["NOW","FIRST_USE","ON_DEMAND"]},"callback":{"description":"URL for order status webhook notifications","type":["string","null"]}}}}},"required":true}}}}}
```