Guide: Manage subscription updates

Overview

When existing subscribers want to upgrade, downgrade, or add extras to their subscription, you need a checkout flow that understands their current state. The Subscription Checkout API provides a stateful basket that:

• Knows what the subscriber currently has (their active offer and add-ons)

• Calculates what they can change to (upgrades, downgrades, cross-sells)

• Handles the business logic automatically (removing old offers when adding new ones, checking compatibility)

This gives you several advantages:

• No eligibility logic in the browser. The API determines valid upgrade/downgrade paths based on your Limio configuration.

• Automatic state management. When a subscriber selects a new offer, the system auto-generates the remove action for their current offer.

• Cleaner add-on handling. Incompatible add-ons are automatically flagged for removal when switching offers.

Prerequisites

• Access to the Limio Commerce API with a valid Bearer token (for standard flow) or Partner token (for partner integrations)

• An active subscription

• (Optional) Upgrade/downgrade paths configured on your Offers in Limio

What you'll build

1. Initiate a subscription checkout session by providing the subscription ID. The API returns available upgrades, downgrades, and cross-sells.

2. Update the basket by adding offers or add-ons. The system calculates prices and generates any required remove actions.

3. Retrieve the basket state at any point (e.g., after page refresh) to continue the checkout.

---

Initiate the checkout session

Use POST api/checkout/subscription to create a basket for the subscriber. At minimum, provide:

• order.forSubscription.id — the subscription ID to modify

• order.order_type — must be "update_subscription"

Example — initiate checkout (curl)

curl -X POST 'https://your-tenant.limio.com/api/checkout/subscription' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'xLimioRecaptcha: <RECAPTCHA_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "forSubscription": {
        "id": "sub_abc123"
      },
      "order_type": "update_subscription"
    }
  }'

Notes:

• forSubscription accepts either id or name to identify the subscription

Response

{
  "order": {
    "checkoutId": "basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364",
    "forSubscription": { "id": "sub_abc123", "name": "Premium Monthly" },
    "forSubscriptionOffer": { "offerId": "offer_premium_monthly" },
    "orderItems": [],
    "total": { "currency": "USD", "amount": 0 }
  },
  "nextActions": {
    "upgrades": [
      { "id": "offer_premium_annual", "name": "Premium Annual" }
    ],
    "downgrades": [
      { "id": "offer_basic_monthly", "name": "Basic Monthly" }
    ],
    "crossSells": [
      { "id": "addon_extra_storage", "name": "Extra Storage" }
    ],
    "subscriptionAddOns": []
  },
  "completed": false
}

The response tells you:

• checkoutId — the basket ID (also set in limio_state cookie)

• forSubscriptionOffer — what the subscriber currently has

• nextActions.upgrades / downgrades — valid offer changes based on your Limio config

• nextActions.crossSells — available add-ons

• nextActions.subscriptionAddOns — add-ons they already own

Error responses

Status	Meaning	Resolution
423	Subscription has a pending change scheduled	Wait until pendingChangeDate passes
404	Subscription not found or not owned by user	Verify subscription ID and auth token
400	Invalid request body	Check schema requirements

---

Update the basket with offers or add-ons

Use PUT api/checkout/subscription to add or remove items. The landing state lmo_ls cookie (set by POST) must be present.

Example — select an upgrade (curl)

curl -X PUT 'https://your-tenant.limio.com/api/checkout/subscription' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'xLimioRecaptcha: <RECAPTCHA_TOKEN>' \
  -H 'Cookie: lmo_ls=...' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "forSubscription": { "id": "sub_abc123" },
      "order_type": "update_subscription",
      "orderItems": [
        {
          "orderItemActionType": "add",
          "type": "offer",
          "offerId": "offer_premium_annual"
        }
      ]
    }
  }'

What happens automatically

When you add a new subscription offer, the system:

1. Generates a remove action for the current offer (forSubscriptionOffer) if relevant

2. Checks add-on compatibility and generates remove actions for incompatible add-ons

3. Calculates prices and line items for all order items

4. Recalculates cross-sells based on the new offer selection

Response

{
  "order": {
    "checkoutId": "basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364",
    "orderItems": [
      {
        "id": "item-uuid-1",
        "orderItemActionType": "add",
        "type": "offer",
        "offerId": "offer_premium_annual",
        "price": { "amount": 99.0, "currency": "USD" }
      },
      {
        "id": "item-uuid-2",
        "orderItemActionType": "remove",
        "type": "offer",
        "offerId": "offer_premium_monthly"
      }
    ],
    "effectiveDate": "2025-01-15T00:00:00.000Z",
    "total": { "currency": "USD", "amount": 99.0 }
  },
  "nextActions": {
    "upgrades": [],
    "downgrades": [],
    "crossSells": []
  }
}

Adding multiple add-ons

Each PUT replaces orderItems entirely (upgrades/downgrades persist from POST, crossSells are recalculated). To add multiple add-ons, include them all in one request:

curl -X PUT 'https://your-tenant.limio.com/api/checkout/subscription' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'xLimioRecaptcha: <RECAPTCHA_TOKEN>' \
  -H 'Cookie: lmo_ls=...' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "forSubscription": { "id": "sub_abc123" },
      "order_type": "update_subscription",
      "orderItems": [
        { "orderItemActionType": "add", "type": "addon", "offerId": "addon_storage" },
        { "orderItemActionType": "add", "type": "addon", "offerId": "addon_support" }
      ]
    }
  }'

Validation rules

• One offer add per request — you can only add one subscription offer at a time (add-ons have no limit)

• Basket ownership — the basket must belong to the authenticated user/partner

---

Retrieve the basket

Use GET api/checkout/subscription to fetch the current basket state. Useful after page refresh or to verify state before payment.

curl -X GET 'https://your-tenant.limio.com/api/checkout/subscription' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Cookie: limio_state=...'

Response structure is identical to POST/PUT.

---

Authentication modes

Mode	Endpoint	Auth Header
Standard (MMA)	api/checkout/subscription	Authorization: Bearer <token>
Partner	api/partner/checkout/subscription	X-Partner-Token: <token>

---

End-to-end example (Node.js)

Below is a minimal service that initiates a subscription upgrade flow and returns a checkout URL.

import express from "express";

const app = express();
app.use(express.json());

const LIMIO_BASE = "https://your-tenant.limio.com";

app.post("/upgrade", async (req, res) => {
  const { subscriptionId, upgradeOfferId, token, recaptchaToken } = req.body;

  // 1) Initiate checkout session
  const initResp = await fetch(`${LIMIO_BASE}/api/checkout/subscription`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      xLimioRecaptcha: recaptchaToken,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        forSubscription: { id: subscriptionId },
        order_type: "update_subscription",
      },
    }),
  });

  if (!initResp.ok) {
    return res.status(initResp.status).send(await initResp.text());
  }

  const initData = await initResp.json();
  const cookies = initResp.headers.get("set-cookie");

  // 2) Add upgrade offer to basket
  const updateResp = await fetch(`${LIMIO_BASE}/api/checkout/subscription`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      xLimioRecaptcha: recaptchaToken,
      Cookie: cookies,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        forSubscription: { id: subscriptionId },
        order_type: "update_subscription",
        orderItems: [
          { orderItemActionType: "add", type: "offer", offerId: upgradeOfferId },
        ],
      },
    }),
  });

  if (!updateResp.ok) {
    return res.status(updateResp.status).send(await updateResp.text());
  }

  const basket = await updateResp.json();

  // 3) Return checkout URL
  const checkoutUrl = `https://your-shop.limio.com/manage/checkout?basket=${basket.order.checkoutId}`;
  res.json({ basketId: basket.order.checkoutId, checkoutUrl, basket });
});

app.listen(3000);

---

Tips & troubleshooting

Why am I getting a 423 error? The subscription has a scheduled change (e.g., a pending upgrade that takes effect next billing cycle). You can't modify it until that date passes. Check subscription.data.pendingChangeDate.

Can I add multiple offers at once? No — only one subscription offer can be added per request. The system enforces a 1:1 swap (add new, remove current). Add-ons don't have this restriction.

Do I need to send remove actions manually? No — when you add a new subscription offer, the system auto-generates the remove action for the current offer and any incompatible add-ons.

How long do baskets last? Baskets expire after 14 days. The limio_state cookie tracks the active basket ID.

What's the difference between standard and partner auth? Standard auth (BEARER_MMA) validates the user owns the subscription. Partner auth should be used for admin/CRM integrations where you're acting on behalf of customers.