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
Initiate a subscription checkout session by providing the subscription ID. The API returns available upgrades, downgrades, and cross-sells.
Update the basket by adding offers or add-ons. The system calculates prices and generates any required remove actions.
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 modifyorder.order_type— must be"update_subscription"
Example — initiate checkout (curl)
Notes:
forSubscriptionaccepts eitheridornameto identify the subscription
Response
The response tells you:
checkoutId— the basket ID (also set in thelmo_lslanding-state cookie)forSubscriptionOffer— what the subscriber currently hasnextActions.upgrades/downgrades— valid offer changes based on your Limio confignextActions.crossSells— available add-onsnextActions.subscriptionAddOns— add-ons they already own
Error responses
See Error reference below for the response body and the one status you can branch on.
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)
What happens automatically
When you add a new subscription offer, the system:
Generates a remove action for the current offer (
forSubscriptionOffer) if relevantChecks add-on compatibility and generates remove actions for incompatible add-ons
Calculates prices and line items for all order items
Recalculates cross-sells based on the new offer selection
Response
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:
Removing a subscription offer (Release 116)
To remove an offer from a multi-offer subscription without cancelling it, include one item per offer being removed, with orderItemActionType: "remove" and type: "subscription_offer". The offer.id references the subscription offer — the offer instance on the subscription — not the catalog offer:
Batch all removals into the same request. Removals take effect at the end of the current term; if the same order also adds an offer (a swap), the effective date follows the added offer's upgrade or downgrade classification instead.
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
At least one active offer must remain — an order that would remove every offer on the subscription is rejected; an offer added in the same order offsets a removal (a swap)
Removals require an initiated basket — the server resolves the subscription's current offer versions when the checkout session is initiated
Batch removals into a single order — submitting an update order sets a pending change that locks further update checkouts until the effective date passes (the
423 subscription_lockederror described below)
Retrieve the basket
Use GET api/checkout/subscription to fetch the current basket state. Useful after page refresh or to verify state before payment.
Response structure is identical to POST/PUT.
Authentication modes
Standard (MMA)
api/checkout/subscription
Authorization: Bearer <token>
Partner
api/partner/checkout/subscription
Authorization: Bearer <partner token>
Both modes use a bearer token in the Authorization header; they differ in the endpoint and in the token you present. Standard auth validates that the user owns the subscription. Partner auth is for admin and CRM integrations acting on behalf of customers.
End-to-end example (Node.js)
Below is a minimal service that initiates a subscription upgrade flow and returns a checkout URL.
Error reference
Every error from this endpoint has the same body:
There is no error field. Quote the requestId when contacting support — it is how we find your request in the logs.
Only one failure is individually identifiable. When the subscription has a pending change scheduled, you get a 423 with a specific code:
Branch on code === "subscription_locked" (or the 423 status) and tell the subscriber to try again after pendingChangeDate.
Every other failure — subscription not found, more than one offer added, missing basket, invalid body — currently returns 500 with the generic generic_error body above. You cannot yet distinguish them programmatically, so do not write logic that branches on a 400 or 404 from this endpoint. Treat any non-423 failure as retryable-once, then surface a generic message.
Security & best practices
Send reCAPTCHA on
POSTandPUT. Enforcement is controlled by theanalytics.recaptcha_on_landing_pagetenant setting, so it is not rejected when disabled — but send it, because enabling that setting must not break your integration.Never trust client-side pricing or eligibility. The API is the authority on both; recompute server-side.
Pass cookies through.
GETandPUTneed thelmo_lslanding-state cookie set by the initialPOST.Use
external_idto tie a basket to your CRM or analytics. Maximum 128 characters, and only letters, digits,-and_. A value outside that is rejected.Baskets last 14 days, and on this endpoint that is fixed. (
expiresAfteris configurable on/api/checkout/initiate, but it is not read here — passing it does nothing.)
Related resources
Basket (Cart) — front-end basket integration with the Limio SDK
Authentication — obtaining and refreshing API tokens
When contacting support about a failed request, quote the requestId from the error response.
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? 14 days, fixed on this endpoint. The lmo_ls cookie tracks the active basket.
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. Both present a bearer token in the Authorization header.
Last updated
Was this helpful?

