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. 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.

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

Create a new subscription

external_idstringOptional

Your own external order reference. Useful for correlating Limio orders with records in upstream systems.

Example: EXT-ORD-12345

initiated_sourcestring · enumOptional

Indicates where the order originated. Limio uses shop for storefront orders and salesforce for CRM-initiated orders. Custom values are supported for other integrations.

Example: shopPossible values:

sourcestringOptional

The system that submitted the order. Limio uses shop for storefront submissions and salesforce for CRM submissions.

Example: shop

process_immediatelybooleanOptional

When true, the order is processed synchronously and the response includes the final processing result. When false (default), the order is queued for asynchronous processing.

Default: false

order_typestring · enumRequiredPossible values:

paymentone ofRequired

Payment

orderDatestring · date-timeOptional

the date on which the subscription should start

Example: 2020-01-01T00:00:00Z

checkoutIdstringRequired

the limio session checkout id for this order

Example: basket-22e3d318-92e2-4909-b59c-1265623bc3f6

countrystringRequired

the country code of the customer's purchase location

Example: GB

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-24T20:47:27.743Z",
  "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"
    }
  ]
}