# 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) ```bash curl -X POST 'https://your-tenant.limio.com/api/checkout/subscription' \ -H 'Authorization: Bearer ' \ -H 'xLimioRecaptcha: ' \ -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 ```json { "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) ```bash curl -X PUT 'https://your-tenant.limio.com/api/checkout/subscription' \ -H 'Authorization: Bearer ' \ -H 'xLimioRecaptcha: ' \ -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 ```json { "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: ```bash curl -X PUT 'https://your-tenant.limio.com/api/checkout/subscription' \ -H 'Authorization: Bearer ' \ -H 'xLimioRecaptcha: ' \ -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. ```bash curl -X GET 'https://your-tenant.limio.com/api/checkout/subscription' \ -H 'Authorization: Bearer ' \ -H 'Cookie: limio_state=...' ``` Response structure is identical to POST/PUT. *** ### Authentication modes | Mode | Endpoint | Auth Header | | -------------- | ----------------------------------- | ------------------------------- | | Standard (MMA) | `api/checkout/subscription` | `Authorization: Bearer ` | | Partner | `api/partner/checkout/subscription` | `X-Partner-Token: ` | *** ### End-to-end example (Node.js) Below is a minimal service that initiates a subscription upgrade flow and returns a checkout URL. ```javascript 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.limio.com/guides/developer-guides/guide-manage-subscription-updates.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.