Orders
Submit or preview orders to trigger Limio's order orchestration framework. Supports new subscriptions, offer changes, cancellations, address updates, payment method changes, and gift redemptions.
Submit an order. order_type selects what the order does, and the rest of the body is the payload of that type. This one endpoint therefore covers most of what happens to a subscription after it starts.
Buy a new subscription with new. Cancel one with cancel_subscription, and refund it with refund. Change what the customer has with change_offer, add_offer or update_subscription. Change their details with change_address or update_customer_details. Change how they pay with change_payment, change_default_payment or delete_payment_method. Record an answer they gave with data_capture.
Send the same body to /order/preview first to see the totals, the taxes and the schedule that the order would produce, without submitting it.
If the order is created but immediate processing fails, the response keeps HTTP 200 and adds error_reason plus either a payment or processing section describing what went wrong and whether it is worth retrying.
Optionally include a partner organisation to attribute the order to, run partner-specific eligibility checks, and associate the order and all its related objects with the partner organisation.
OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.
Obtain a token via the OAuth flow described in OAuth Bearer Token.
Pass the token in the Authorization header: Bearer <token>
OK
Response returned after successfully submitting an order.
Unique identifier of the created order.
order-4dd195c3eee4297e33aecb5436cf8092Human-readable order reference code.
8HK92PL401QWStatus of the order event at the time of the response. New submissions return submitted, or pending-payment when the order carries no payment details yet (new orders and payment changes that redirect to a payment provider). Resubmitting an order with an external_id that was already submitted returns the stored event's current status instead, which may reflect later processing.
submittedThe external order reference provided in the request, if any.
EXT-ORD-12345Reference code of the subscription created or modified by this order.
2TJ25TK632EGThe identity ID that owns objects created by this order.
id-62401f8d5bf6b26a37ea0defd66fd005The webhook endpoint configured for this order type in the webhooks.order setting, if any.
https://example.com/webhooks/orderError message when the order event was created but immediate processing failed. Absent on success.
Present only alongside error. Names the section that describes the failure: payment for a payment or gateway failure (see the payment object), or processing for any other processing failure (see the processing array).
paymentPossible values: Invalid partner organisation
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Not found
Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.
POST /api/admin/order HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 612
{
"order_type": "new",
"external_id": "EXT-ORD-12345",
"checkoutId": "basket-22e3d318-92e2-4909-b59c-1265623bc3f6",
"country": "GB",
"orderItems": [
{
"offer": {
"id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
"version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
},
"quantity": 1
}
],
"customerDetails": {
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"billingDetails": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "10 Downing Street",
"city": "London",
"postalCode": "SW1A 2AA",
"country": "GB"
},
"payment": {
"type": "zuora",
"zuora": {
"refId": "2c92c0f96e4e3b7f016e5f3b3b7b0b3d",
"paymentGateway": "CreditCard_UK"
}
}
}{
"id": "order-4dd195c3eee4297e33aecb5436cf8092",
"order_reference": "8HK92PL401QW",
"status": "submitted",
"external_id": "EXT-ORD-12345",
"subscriptionReference": "2TJ25TK632EG",
"owner": "id-62401f8d5bf6b26a37ea0defd66fd005",
"customer_endpoint": "https://example.com/webhooks/order",
"error": "text",
"error_reason": "payment",
"payment": {
"processor": "zuora",
"reason": "generic_decline",
"processorError": {
"code": "203",
"message": "REJECT"
},
"retry": "payment_method"
},
"processing": [
{
"name": "salesforce",
"message": "more than one customer record found for an identity",
"category": "hard",
"retry": "none",
"critical": true
}
]
}Answers what an order would cost and change, without submitting it. Send the same body as POST /admin/order and read back the totals, the tax, the credit or refund amount, the effective date and the schedule of future charges. Use it to quote a price, to show a customer what a change means before they confirm, or to check an order before you send it.
It previews every order type that the order endpoint accepts: a new subscription, an offer change, a cancellation, a refund or credit memo, a gift refund and a subscription update.
Session-scoped Bearer token for authenticated end-user operations. Used by the Limio SDK to retrieve user-specific data such as entitlements. Tokens are issued during the checkout or login flow.
OK
Preview response returned by the order preview endpoint. Contains the raw billing provider result and a normalised payment schedule that front-end consumers use to display pricing summaries.
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Not found
Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.
POST /api/order/preview HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 582
{
"order_type": "new",
"checkoutId": "basket-22e3d318-92e2-4909-b59c-1265623bc3f6",
"country": "GB",
"orderItems": [
{
"offer": {
"id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
"version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
},
"quantity": 1
}
],
"customerDetails": {
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com"
},
"billingDetails": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "10 Downing Street",
"city": "London",
"postalCode": "SW1A 2AA",
"country": "GB"
},
"payment": {
"type": "zuora",
"zuora": {
"refId": "2c92c0f96e4e3b7f016e5f3b3b7b0b3d",
"paymentGateway": "CreditCard_UK"
}
}
}{
"preview": {
"success": true,
"orderNumber": "67JKSCLQESR0",
"orderId": "8ad0887e850fc589018512981a1b4acb",
"accountNumber": "A-000000000",
"status": "active",
"subscriptions": [
{
"status": "active",
"subscriptionId": "8ad0887e850fc589018512981a1b4acb",
"subscriptionNumber": "S-000000000"
}
],
"paymentNumber": "P-000000000",
"paymentId": "8ad0887e850fc589018512981a1b4acb",
"paidAmount": "19.99",
"previewResult": {
"invoices": [
{
"amount": 19.99,
"amountWithoutTax": 19.99,
"targetDate": "2020-05-01T00:00:00Z",
"taxAmount": 0,
"invoiceItems": {
"additionalInfo": {
"quantity": 1,
"unitOfMeasure": "Each"
},
"amountWithoutTax": 19.99,
"chargeDescription": "Monthly subscription",
"chargeName": "Charge",
"chargeNumber": "C-000000000",
"processingType": "Charge",
"productName": "Product",
"productRatePlanChargeId": "2c98901f6706718c016706b91c6e001f",
"serviceEndDate": "2020-05-01T00:00:00Z",
"serviceStartDate": "2020-05-01T00:00:00Z",
"subscriptionNumber": "S-000000000",
"taxAmount": 0,
"unitPrice": 19.99
}
}
],
"creditMemos": [
{
"amount": 19.99,
"amountWithoutTax": 19.99,
"targetDate": "2020-05-01T00:00:00Z",
"taxAmount": 0,
"creditMemoItems": [
{
"additionalInfo": {
"quantity": 1,
"unitOfMeasure": "Each"
},
"amountWithoutTax": 19.99,
"chargeDescription": "Monthly subscription",
"chargeName": "Charge",
"chargeNumber": "C-000000000",
"processingType": "Charge",
"productName": "Product",
"productRatePlanChargeId": "2c98901f6706718c016706b91c6e001f",
"serviceEndDate": "2020-05-01T00:00:00Z",
"serviceStartDate": "2020-05-01T00:00:00Z",
"subscriptionNumber": "S-000000000",
"taxAmount": 0,
"unitPrice": 19.99
}
]
}
]
}
},
"schedule": [
{
"date": "2020-05-01T00:00:00.000",
"schedule_date": "2020-05-01T00:00:00.000",
"type": "payment",
"amount": "19.99",
"taxAmount": 0,
"amountWithoutTax": "19.99",
"currency": "GBP",
"unit_amount": "19.99",
"quantity": 1,
"hasDiscount": false,
"amountExcludingDiscount": "19.99",
"discountUnitValue": "0.00",
"lineItems": [
{
"amountWithoutTax": "19.99",
"taxAmount": "0.00",
"limioCatalogObjectId": "offer-new-offer-id",
"processingType": "Charge",
"chargeName": "Monthly",
"productName": "Premium Digital",
"quantity": 1
}
],
"taxSummary": [
{
"taxCode": "VAT",
"taxRate": 0.2,
"taxAmount": 5
}
],
"reference": "S-000000000"
}
]
}Check a gift code before you redeem it. Limio makes sure that the code exists, is not redeemed, and is not expired.
A valid code returns the items that the purchaser paid for, with every price set to zero, plus the recipient details from the gift purchase. Use these values to build the redemption order that you send to Submit Order.
An invalid code also returns HTTP 200. Read success and error.code to find the reason. This call does not redeem the code, so you can repeat it.
OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.
Obtain a token via the OAuth flow described in OAuth Bearer Token.
Pass the token in the Authorization header: Bearer <token>
The gift code. A code that Limio generates has 11 letters and digits. The code is case-sensitive.
k3TgR8mWq2ZThe ID of a subscription that the recipient already has. When you supply it, the response adds an order_type: credit when that subscription renews automatically, renew when it does not. With credit, the items keep their prices so that you know the value of the gift.
The result of the check. A valid code returns the gift details. An invalid code returns success: false and an error.
Unauthorized: the request lacks valid authentication credentials. This response is returned by the API gateway before the request reaches the application. Verify your Bearer token is correct and has not expired.
POST /api/validate/gift/{id} HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"subscriptionId": "text"
}{
"giftCode": "k3TgR8mWq2Z",
"orderItems": [
{
"offer": {
"id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
"version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
},
"quantity": 1
}
],
"country": "GB",
"recipientDetails": {
"firstName": "Alice",
"lastName": "Johnson",
"email": "alice.johnson@example.com",
"message": "Happy Christmas. Enjoy your subscription."
},
"deliveryDetails": {
"country": "GB"
},
"total": {
"amount": 179,
"currency": "GBP"
}
}Last updated
Was this helpful?