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 Order

post

Submit an order directly to Limio. This will apply the changes immediately and can be used to update a subscription, change the offer, or update customer details.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Body

application/json

or

or

or

or

or

or

or

or

or

Responses

200

OK

application/json

Response returned after successfully submitting an order.

idstringOptional

Unique identifier of the created order.

Example: order-4dd195c3eee4297e33aecb5436cf8092

order_referencestringOptional

Human-readable order reference code.

Example: 8HK92PL401QW

statusstring · enumOptional

Processing status of the order.

Example: completePossible values:

external_idstringOptional

The external order reference provided in the request, if any.

Example: EXT-ORD-12345

subscriptionReferencestringOptional

Reference code of the subscription created or modified by this order.

Example: 2TJ25TK632EG

ownerstringOptional

The identity ID that owns objects created by this order.

Example: id-62401f8d5bf6b26a37ea0defd66fd005

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

Not found

502

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.

application/json

post

/order

HTTPcURLJavaScriptPython

POST /api/order HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2115

{
  "external_id": "EXT-ORD-12345",
  "initiated_source": "shop",
  "source": "shop",
  "process_immediately": false,
  "order_type": "new",
  "orderItems": [
    {
      "offer": {
        "id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
        "version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
      },
      "quantity": 1
    }
  ],
  "orderDiscount": {
    "name": "TEST123",
    "productDetails": {
      "ratePlan": {
        "path": "30% Off Monthly"
      },
      "product": {
        "path": "/products/Discounts"
      }
    },
    "product": {
      "baseTemplate": "/config/templates/products/default",
      "entitlements": [
        {
          "$ref": "/entitlements/Digital"
        }
      ],
      "path": "/products/Digital",
      "created": "2023-12-11T13:44:43+00:00",
      "modified": "2024-01-15T13:56:18+00:00",
      "attributes": {
        "display_name__limio": "Digital",
        "has_delivery__limio": false,
        "product_code__limio": "LI.DIGITAL"
      },
      "record_type": "product",
      "lastSynced": "2024-03-12T16:00:35.232Z",
      "synced": true,
      "syncedFrom": "2c92c0f9778c090d0177aa4f357d043b"
    },
    "discountOverrides": {
      "discountType": "DiscountPercentage",
      "durationLength": 1,
      "durationType": "Months",
      "percentageDiscount": 10,
      "amountDiscount": 10,
      "currency": "USD",
      "orderItemsWithSpecifiedDiscount": {
        "discountedOffers": []
      }
    }
  },
  "billingDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  },
  "deliveryDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  },
  "customerDetails": {
    "firstName": "text",
    "lastName": "text",
    "phone": "text",
    "email": "text"
  },
  "tracking": {
    "offers": [
      "/offers2/$75 for 52 weeks then $31.96 every 4 weeks autorenew"
    ],
    "purchaseCountryCode": "GB",
    "accountId": "0017x00000Q9O9qAAF",
    "contactId": "0037x00000F58M9AAJ",
    "userId": "0057x0000088Oh3AAE"
  },
  "payment": {
    "type": "zuora",
    "zuora": {
      "refId": "2c92c0f96e4e3b7f016e5f3b3b7b0b3d",
      "paymentGateway": "CreditCard_UK"
    }
  },
  "orderDate": "2020-01-01T00:00:00Z",
  "checkoutId": "basket-22e3d318-92e2-4909-b59c-1265623bc3f6",
  "country": "GB"
}

{
  "id": "order-4dd195c3eee4297e33aecb5436cf8092",
  "order_reference": "8HK92PL401QW",
  "status": "complete",
  "external_id": "EXT-ORD-12345",
  "subscriptionReference": "2TJ25TK632EG",
  "owner": "id-62401f8d5bf6b26a37ea0defd66fd005"
}

Submit Order as Admin

post

Submit an order using management credentials. Admin users can optionally include a partner organisation to attribute the order to and run partner-specific eligibility checks and associate the order, and all its related objects with the partner organisation.

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Body

application/json

Responses

200

OK

application/json

Response returned after successfully submitting an order.

idstringOptional

Unique identifier of the created order.

Example: order-4dd195c3eee4297e33aecb5436cf8092

order_referencestringOptional

Human-readable order reference code.

Example: 8HK92PL401QW

statusstring · enumOptional

Processing status of the order.

Example: completePossible values:

external_idstringOptional

The external order reference provided in the request, if any.

Example: EXT-ORD-12345

subscriptionReferencestringOptional

Reference code of the subscription created or modified by this order.

Example: 2TJ25TK632EG

ownerstringOptional

The identity ID that owns objects created by this order.

Example: id-62401f8d5bf6b26a37ea0defd66fd005

400

Invalid partner organisation or malformed order payload.

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

Not found

502

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.

application/json

post

/admin/order

HTTPcURLJavaScriptPython

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: 2153

{
  "forPartner": {
    "id": "partner_org-123"
  },
  "external_id": "EXT-ORD-12345",
  "initiated_source": "shop",
  "source": "shop",
  "process_immediately": false,
  "order_type": "new",
  "orderItems": [
    {
      "offer": {
        "id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
        "version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
      },
      "quantity": 1
    }
  ],
  "orderDiscount": {
    "name": "TEST123",
    "productDetails": {
      "ratePlan": {
        "path": "30% Off Monthly"
      },
      "product": {
        "path": "/products/Discounts"
      }
    },
    "product": {
      "baseTemplate": "/config/templates/products/default",
      "entitlements": [
        {
          "$ref": "/entitlements/Digital"
        }
      ],
      "path": "/products/Digital",
      "created": "2023-12-11T13:44:43+00:00",
      "modified": "2024-01-15T13:56:18+00:00",
      "attributes": {
        "display_name__limio": "Digital",
        "has_delivery__limio": false,
        "product_code__limio": "LI.DIGITAL"
      },
      "record_type": "product",
      "lastSynced": "2024-03-12T16:00:35.232Z",
      "synced": true,
      "syncedFrom": "2c92c0f9778c090d0177aa4f357d043b"
    },
    "discountOverrides": {
      "discountType": "DiscountPercentage",
      "durationLength": 1,
      "durationType": "Months",
      "percentageDiscount": 10,
      "amountDiscount": 10,
      "currency": "USD",
      "orderItemsWithSpecifiedDiscount": {
        "discountedOffers": []
      }
    }
  },
  "billingDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  },
  "deliveryDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  },
  "customerDetails": {
    "firstName": "text",
    "lastName": "text",
    "phone": "text",
    "email": "text"
  },
  "tracking": {
    "offers": [
      "/offers2/$75 for 52 weeks then $31.96 every 4 weeks autorenew"
    ],
    "purchaseCountryCode": "GB",
    "accountId": "0017x00000Q9O9qAAF",
    "contactId": "0037x00000F58M9AAJ",
    "userId": "0057x0000088Oh3AAE"
  },
  "payment": {
    "type": "zuora",
    "zuora": {
      "refId": "2c92c0f96e4e3b7f016e5f3b3b7b0b3d",
      "paymentGateway": "CreditCard_UK"
    }
  },
  "orderDate": "2020-01-01T00:00:00Z",
  "checkoutId": "basket-22e3d318-92e2-4909-b59c-1265623bc3f6",
  "country": "GB"
}

{
  "id": "order-4dd195c3eee4297e33aecb5436cf8092",
  "order_reference": "8HK92PL401QW",
  "status": "complete",
  "external_id": "EXT-ORD-12345",
  "subscriptionReference": "2TJ25TK632EG",
  "owner": "id-62401f8d5bf6b26a37ea0defd66fd005"
}

Preview Order

post

Preview an order in Limio to see the changes that will be applied. This can be used to show the user what will happen before they confirm the order, including changes to future charges, the effective date of the change, and any other details. Supports previewing new subscriptions, offer changes, cancellations, credit memos, gift refunds, and subscription updates.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Body

application/json

or

or

or

or

or

or

Responses

200

OK

application/json

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

Not found

502

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.

application/json

post

/order/preview

HTTPcURLJavaScriptPython

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: 957

{
  "external_id": "EXT-ORD-12345",
  "initiated_source": "shop",
  "source": "shop",
  "process_immediately": false,
  "order_type": "change_offer",
  "forSubscription": {
    "name": "text"
  },
  "offer": {
    "id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
    "version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
  },
  "effectiveDate": "2026-03-06T16:32:28.496Z",
  "payment": {
    "type": "zuora",
    "zuora": {
      "refId": "2c92c0f96e4e3b7f016e5f3b3b7b0b3d",
      "paymentGateway": "CreditCard_UK"
    }
  },
  "billingDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  },
  "deliveryDetails": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "workEmail": "text",
    "phone": "text",
    "workPhone": "text",
    "otherPhone": "text",
    "company": "text",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "postalCode": "text",
    "country": "text"
  }
}

{
  "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:00Z",
      "schedule_date": "2020-05-01T00:00:00Z",
      "type": "Schedule",
      "description": "Schedule",
      "amount": "19.99",
      "taxAmount": 0,
      "amountWithoutTax": "19.99",
      "currency": "GBP",
      "lineItems": [
        {
          "amountWithoutTax": 19.99,
          "processingType": "Charge",
          "taxAmount": "0.00",
          "chargeDescription": "Charge",
          "chargeName": "Charge",
          "productName": "Product",
          "quantity": 1
        }
      ],
      "quantity": 1,
      "reference": "S-000000000",
      "unit_amount": "19.99"
    }
  ]
}