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

and

anyOptional

or

or

or

or

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

400

Invalid partner organisation

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: 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": "[e-mail]"
  },
  "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"
    }
  }
}

Create a new subscriptionCreate a subscription attributed to a partnerPurchase a gift subscriptionRedeem a gift subscriptionChange the offer on a subscriptionAdd a discounted offer to a subscriptionCancel a subscriptionCancel a subscription at end of termRefund a gift subscriptionSubmit a previously prepared subscription updateUpdate customer details on a subscriptionChange billing addressChange default Zuora payment methodChange payment method (pending — payment collected via MMA checkout)Change payment method (with Stripe token)Change payment method (invoice)Delete a payment methodSubmit data from a Data Capture Form

{
  "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

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.

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: 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": "[e-mail]"
  },
  "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 a new subscriptionPreview an offer changePreview adding a discounted offerPreview a cancellationPreview a gift refundPreview an offer upgrade with add-on removalPreview a quantity increase

{
  "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"
    }
  ]
}