Orders API

Submit new orders to the Limio platform for processing and integration with downstream systems, supporting order capture for subscriptions, trials, and offers.

You can send Preview and Send Orders into Limio to trigger Limio's Order Orchestration framework. The full API documentation is available at Limio Order REST API Documentation.

Key requests are listed below.

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

To create a Bearer token, see How to get an OAuth Bearer Token?.

Usage format: Bearer <token>

Body

application/json

or

or

or

or

or

or

or

or

or

or

Responses

200

OK

application/json

401

Unauthorized

application/json

404

Not found

502

Bad Gateway

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

{
  "external_id": "text",
  "initiated_source": "text",
  "source": "text",
  "process_immediately": true,
  "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": "text",
  "order_reference": "text",
  "status": "text",
  "external_id": "text",
  "subscriptionReference": "text",
  "owner": "text"
}

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

To create a Bearer token, see How to get an OAuth Bearer Token?.

Usage format: Bearer <token>

Body

application/json

or

or

Responses

200

OK

application/json

401

Unauthorized

application/json

404

Not found

502

Bad Gateway

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

{
  "external_id": "text",
  "initiated_source": "text",
  "source": "text",
  "process_immediately": true,
  "order_type": "change_offer",
  "forSubscription": {
    "name": "text"
  },
  "offer": {
    "id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
    "version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
  },
  "effectiveDate": "2025-12-29T07:46:24.439Z",
  "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-01",
          "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-01",
            "serviceStartDate": "2020-05-01",
            "subscriptionNumber": "S-000000000",
            "taxAmount": 0,
            "unitPrice": 19.99
          }
        }
      ],
      "creditMemos": [
        {
          "amount": 19.99,
          "amountWithoutTax": 19.99,
          "targetDate": "2020-05-01",
          "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-01",
              "serviceStartDate": "2020-05-01",
              "subscriptionNumber": "S-000000000",
              "taxAmount": 0,
              "unitPrice": 19.99
            }
          ]
        }
      ]
    }
  },
  "schedule": [
    {
      "date": "2020-05-01",
      "schedule_date": "2020-05-01",
      "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"
    }
  ]
}