Legacy
Legacy checkout endpoints, kept for backward compatibility. They authenticate via the Limio shop user session and landing-state cookie, so they can only be called from the Limio shop or Self-Service — they are not usable for external integrations. For programmatic checkout, use the New Subscription and Renew Subscription APIs instead.
Legacy — kept for backward compatibility. Authenticates via the Limio shop user session and landing-state cookie, so it can only be called from the Limio shop or Self-Service; it is not usable for external integrations.
Update an existing checkout basket with order item actions — add items, remove items, or change quantities. The basket ID is read from the landing state cookie. Returns the updated order and action results.
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>
Landing state cookie containing the basketId.
Basket updated successfully.
The basket ID.
The updated order.
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Basket not found in landing state.
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.
PUT /api/checkout/update HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Cookie: text
Content-Type: application/json
Accept: */*
Content-Length: 134
{
"orderActions": [
{
"orderItemActionType": "add",
"offerId": "text",
"orderItemId": "text",
"quantity": 1,
"version": "text",
"parentId": "text"
}
]
}{
"id": "text",
"order": {},
"orderActionResults": [
{
"id": "text",
"actionType": "add"
}
]
}Legacy — kept for backward compatibility. Authenticates via the Limio shop user session and landing-state cookie, so it can only be called from the Limio shop or Self-Service; it is not usable for external integrations.
Fetch existing basket by basketId from landing state cookie. Used to retrieve current checkout state after page refresh or navigation.
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>
Landing state cookie containing basketId
Basket retrieved successfully
Unique basket identifier
basket-12345-uuidWhether the checkout is completed
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Access denied (for example partner or data-scope access failure)
The basket referenced by the landing state cookie no longer exists
The authenticated user does not own the basket (triggers the clone-checkout flow)
Application error. Returned when the landing state cookie contains no basketId, or when the basket has expired
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.
GET /api/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Cookie: text
Accept: */*
{
"id": "basket-12345-uuid",
"order": {
"checkoutId": "basket-12345-uuid",
"external_id": "text",
"order_type": "update_subscription",
"forSubscription": {
"id": "text",
"name": "text"
},
"forSubscriptionOffer": {
"offerId": "text"
},
"orderItems": [
{
"id": "text",
"orderItemActionType": "add",
"type": "offer",
"offerId": "text",
"quantity": 1,
"price": {},
"orderLineItem": {},
"effective_date": "2026-01-01T00:00:00.000Z"
}
],
"country": "US",
"source": "shop",
"effectiveDate": "2026-01-01T00:00:00.000Z",
"total": {
"currency": "USD",
"orderSubtotal": 1,
"orderTotal": 1,
"totalOrderDiscounts": 1,
"amount": 1
}
},
"nextActions": {
"upgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"downgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"crossSells": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"subscriptionAddOns": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"selectOffer": true
},
"completed": true
}Legacy — kept for backward compatibility. Authenticates via the Limio shop user session and landing-state cookie, so it can only be called from the Limio shop or Self-Service; it is not usable for external integrations.
Create a new basket for update subscription with available upgrade/downgrade options. This is the first step in updating a subscription - it creates a basket and returns available actions.
Returns:
Basket with available upgrades, downgrades, cross-sells, and add-ons
Sets landing state cookie with basketId for subsequent requests
Status 423: Subscription has pending change (locked until date passes)
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>
reCAPTCHA token for bot prevention
Client IP address
Referrer URL for journey tracking
Optional tracking data for analytics and reporting
Checkout basket created successfully
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Subscription has pending change, checkout locked
Application error. Returned when the request body is invalid, or when no subscription matches the forSubscription query
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.
POST /api/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Limio-Recaptcha: text
Content-Type: application/json
Accept: */*
Content-Length: 110
{
"order": {
"external_id": "ext-12345",
"forSubscription": {
"id": "sub_abc123"
},
"order_type": "update_subscription"
}
}{
"id": "basket-12345-uuid",
"order": {
"checkoutId": "basket-12345-uuid",
"external_id": "text",
"order_type": "update_subscription",
"forSubscription": {
"id": "text",
"name": "text"
},
"forSubscriptionOffer": {
"offerId": "text"
},
"orderItems": [
{
"id": "text",
"orderItemActionType": "add",
"type": "offer",
"offerId": "text",
"quantity": 1,
"price": {},
"orderLineItem": {},
"effective_date": "2026-01-01T00:00:00.000Z"
}
],
"country": "US",
"source": "shop",
"effectiveDate": "2026-01-01T00:00:00.000Z",
"total": {
"currency": "USD",
"orderSubtotal": 1,
"orderTotal": 1,
"totalOrderDiscounts": 1,
"amount": 1
}
},
"nextActions": {
"upgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"downgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"crossSells": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"subscriptionAddOns": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"selectOffer": true
},
"completed": true
}Legacy — kept for backward compatibility. Authenticates via the Limio shop user session and landing-state cookie, so it can only be called from the Limio shop or Self-Service; it is not usable for external integrations.
Update existing basket with order items (add/remove offers and add-ons).
Business Logic:
Only 1 add offer allowed per request
System auto-adds remove action for current subscription offer when adding new offer
System auto-removes incompatible add-ons when switching subscription offers
System calculates prices, line items, and effective dates
Cross-sells are recalculated based on updated basket
Requirements:
basketId must be present in landing state cookie (from POST response)
Basket must belong to authenticated user
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>
reCAPTCHA token for bot prevention
Landing state cookie containing basketId
Basket updated successfully
Unique basket identifier
basket-12345-uuidWhether the checkout is completed
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Application error. Returned when the request body is invalid, when more than one add offer is provided, or when the landing state cookie contains no basketId
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.
PUT /api/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
X-Limio-Recaptcha: text
Cookie: text
Content-Type: application/json
Accept: */*
Content-Length: 190
{
"order": {
"forSubscription": {
"id": "sub_abc123"
},
"order_type": "update_subscription",
"orderItems": [
{
"orderItemActionType": "add",
"type": "offer",
"offerId": "offer_premium_annual",
"quantity": 1
}
]
}
}{
"id": "basket-12345-uuid",
"order": {
"checkoutId": "basket-12345-uuid",
"external_id": "text",
"order_type": "update_subscription",
"forSubscription": {
"id": "text",
"name": "text"
},
"forSubscriptionOffer": {
"offerId": "text"
},
"orderItems": [
{
"id": "text",
"orderItemActionType": "add",
"type": "offer",
"offerId": "text",
"quantity": 1,
"price": {},
"orderLineItem": {},
"effective_date": "2026-01-01T00:00:00.000Z"
}
],
"country": "US",
"source": "shop",
"effectiveDate": "2026-01-01T00:00:00.000Z",
"total": {
"currency": "USD",
"orderSubtotal": 1,
"orderTotal": 1,
"totalOrderDiscounts": 1,
"amount": 1
}
},
"nextActions": {
"upgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"downgrades": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"crossSells": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"subscriptionAddOns": [
{
"id": "offer_premium_monthly",
"name": "Premium Monthly Plan",
"description": "text",
"price": {
"currency": "USD",
"amount": 29.99
},
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
],
"selectOffer": true
},
"completed": true
}Last updated
Was this helpful?