> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/api/checkout-baskets-api/legacy.md).

# 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.

## Update existing checkout basket for new subscription

> \*\*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.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Legacy","description":"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."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":["checkout"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"502Response":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/checkout/update":{"put":{"operationId":"updateCheckout","summary":"Update existing checkout basket for new subscription","tags":["Legacy"],"description":"**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.\n\nUpdate 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.","parameters":[{"name":"Cookie","in":"header","required":true,"schema":{"type":"string"},"description":"Landing state cookie containing the basketId."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderActions"],"properties":{"orderActions":{"type":"array","description":"List of actions to apply to the basket.","items":{"type":"object","required":["orderItemActionType"],"properties":{"orderItemActionType":{"type":"string","enum":["add","remove","change_quantity"]},"offerId":{"type":"string","description":"Offer ID (required for `add` actions)."},"orderItemId":{"type":"string","description":"Order item ID (required for `remove` and `change_quantity` actions)."},"quantity":{"type":"integer","description":"New quantity (required for `change_quantity` actions)."},"version":{"type":"string","description":"Offer version (optional, for `add` actions)."},"parentId":{"type":"string","description":"Parent item ID for add-on items (optional, for `add` actions)."}}}}}}}}},"responses":{"200":{"description":"Basket updated successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","order","orderActionResults"],"properties":{"id":{"type":"string","description":"The basket ID."},"order":{"type":"object","description":"The updated order."},"orderActionResults":{"type":"array","description":"Results for each action performed.","items":{"type":"object","properties":{"id":{"type":"string"},"actionType":{"type":"string","enum":["add","remove","change_quantity"]}}}}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Basket not found in landing state."},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Retrieve existing checkout basket to update subscription

> \*\*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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Legacy","description":"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."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"502Response":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/checkout/subscription":{"get":{"operationId":"getSubscriptionCheckout","summary":"Retrieve existing checkout basket to update subscription","tags":["Legacy"],"description":"**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.\n\nFetch existing basket by basketId from landing state cookie. Used to retrieve current checkout state after page refresh or navigation.\n","parameters":[{"name":"Cookie","in":"header","required":true,"schema":{"type":"string"},"description":"Landing state cookie containing basketId"}],"responses":{"200":{"description":"Basket retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"No basket found in landing state","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Create checkout basket to update subscription

> \*\*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)<br>

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Legacy","description":"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."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"InitiateSubscriptionCheckoutRequest":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["forSubscription","order_type"],"properties":{"external_id":{"type":"string","maxLength":128,"pattern":"^[0-9a-zA-Z-_]+$","description":"External identifier for tracking purposes"},"checkoutId":{"type":"string","description":"Optional checkout identifier (usually auto-generated)"},"forSubscription":{"type":"object","description":"Target subscription for modification (id or name required)","properties":{"id":{"type":"string","description":"Subscription ID"},"name":{"type":"string","description":"Subscription reference"}},"anyOf":[{"required":["id"]},{"required":["name"]}]},"forSubscriptionOffer":{"type":"object","description":"Optional - Pre-select target offer for subscription modification","properties":{"offerId":{"type":"string","description":"Target offer ID to switch to"}}},"order_type":{"type":"string","enum":["update_subscription"],"description":"Must be \"update_subscription\" for subscription modifications"},"orderItems":{"type":"array","description":"Optional initial order items","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}}}},"tracking":{"type":"object","description":"Optional tracking data for analytics and reporting"}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"502Response":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/checkout/subscription":{"post":{"operationId":"initiateSubscriptionCheckout","summary":"Create checkout basket to update subscription","tags":["Legacy"],"description":"**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.\n\nCreate a new basket for update subscription with available upgrade/downgrade options.\nThis is the first step in updating a subscription - it creates a basket and returns available actions.\n\n**Returns:**\n- Basket with available upgrades, downgrades, cross-sells, and add-ons\n- Sets landing state cookie with basketId for subsequent requests\n\n**Status 423:** Subscription has pending change (locked until date passes)\n","parameters":[{"name":"X-Limio-Recaptcha","in":"header","required":true,"schema":{"type":"string"},"description":"reCAPTCHA token for bot prevention"},{"name":"X-Forwarded-For","in":"header","schema":{"type":"string"},"description":"Client IP address"},{"name":"Referer","in":"header","schema":{"type":"string"},"description":"Referrer URL for journey tracking"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateSubscriptionCheckoutRequest"}}}},"responses":{"200":{"description":"Checkout basket created successfully","headers":{"Set-Cookie":{"description":"Landing state cookie with basketId","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"400":{"description":"Invalid request body or missing required fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"423":{"description":"Subscription has pending change, checkout locked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Update checkout basket to update subscription

> \*\*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<br>

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Legacy","description":"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."}],"servers":[{"url":"https://{tenant}/api","description":"Limio environment API","variables":{"tenant":{"default":"your-environment.prod.limio.com","description":"Your Limio environment hostname, e.g. `acme.prod.limio.com` or `acme-sandbox.prod.limio.com`."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.\n\nObtain a token via the OAuth flow described in [OAuth Bearer Token](https://docs.limio.com/developers/api-documentation/authentication-overview/oauth-bearer-token).\n\nPass the token in the `Authorization` header: `Bearer <token>`"}},"schemas":{"UpdateSubscriptionCheckoutRequest":{"type":"object","required":["order"],"properties":{"order":{"type":"object","required":["forSubscription","order_type"],"properties":{"external_id":{"type":"string","maxLength":128,"pattern":"^[0-9a-zA-Z-_]+$","description":"External identifier for tracking"},"checkoutId":{"type":"string","description":"Checkout identifier from basket"},"forSubscription":{"type":"object","description":"Target subscription reference","properties":{"id":{"type":"string","description":"Subscription ID"},"name":{"type":"string","description":"Subscription name"}}},"order_type":{"type":"string","enum":["update_subscription"],"description":"Must be \"update_subscription\""},"orderItems":{"type":"array","description":"Order items to add/remove (max 1 add offer at a time)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}}}},"tracking":{"type":"object","additionalProperties":true,"description":"Optional tracking data for analytics and reporting"}}},"SubscriptionOrderItem":{"type":"object","required":["orderItemActionType","type"],"properties":{"id":{"type":"string","description":"Auto-generated UUID for the order item"},"orderItemActionType":{"type":"string","enum":["add","remove"],"description":"Action to perform on this item"},"type":{"type":"string","enum":["offer","addon"],"description":"Type of item being added or removed"},"offerId":{"type":"string","description":"ID of the offer or add-on"},"quantity":{"type":"integer","minimum":1,"default":1,"description":"Quantity of the item"},"price":{"type":"object","description":"Price details (calculated by system)","readOnly":true},"orderLineItem":{"type":"object","description":"Line item details (calculated by system)","readOnly":true},"effective_date":{"type":"string","format":"date-time","description":"When this item takes effect (set by system)","readOnly":true}}},"SubscriptionCheckoutResponse":{"type":"object","properties":{"order":{"type":"object","description":"The subscription modification order details","properties":{"checkoutId":{"type":"string","description":"Unique basket identifier"},"external_id":{"type":"string","description":"External tracking identifier"},"order_type":{"type":"string","enum":["update_subscription"]},"forSubscription":{"type":"object","description":"Target subscription being modified","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"forSubscriptionOffer":{"type":"object","description":"Current subscription offer","properties":{"offerId":{"type":"string"}}},"orderItems":{"type":"array","description":"Items in the order (add/remove actions)","items":{"$ref":"#/components/schemas/SubscriptionOrderItem"}},"country":{"type":"string","description":"Purchase country code"},"source":{"type":"string","default":"shop","description":"Source of the order"},"effectiveDate":{"type":"string","format":"date-time","description":"When the subscription changes take effect"},"total":{"type":"object","description":"Order pricing totals","properties":{"currency":{"type":"string"},"orderSubtotal":{"type":"number","description":"Subtotal before discounts"},"orderTotal":{"type":"number","description":"Final total"},"totalOrderDiscounts":{"type":"number","description":"Total discount amount"},"amount":{"type":"number","description":"Amount to be charged"}}}}},"nextActions":{"type":"object","description":"Available actions for the checkout","properties":{"upgrades":{"type":"array","description":"Available upgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"downgrades":{"type":"array","description":"Available downgrade offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"crossSells":{"type":"array","description":"Available cross-sell offers","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"subscriptionAddOns":{"type":"array","description":"Currently owned subscription add-ons","items":{"$ref":"#/components/schemas/SubscriptionOffer"}},"selectOffer":{"type":"boolean","description":"If true, user must select an offer before proceeding"}}},"completed":{"type":"boolean","description":"Whether the checkout is completed"},"context":{"type":"object","description":"Contextual information about the checkout","properties":{"client_ip":{"type":"string","description":"Client IP address"},"requestId":{"type":"string","description":"Unique request identifier"},"identity_id":{"type":"string","description":"User identity identifier"}}},"journey":{"type":"object","description":"User journey tracking data","properties":{"referrer":{"type":"string","description":"Referrer URL"}},"additionalProperties":true}}},"SubscriptionOffer":{"type":"object","description":"Subscription offer or add-on details","properties":{"id":{"type":"string","description":"Offer identifier"},"name":{"type":"string","description":"Offer name"},"description":{"type":"string","description":"Offer description"},"price":{"type":"object","description":"Pricing information","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"attributes":{"type":"object","description":"Additional offer attributes","additionalProperties":true}}}},"responses":{"401Response":{"description":"Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"502Response":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."}}}}}}}},"paths":{"/checkout/subscription":{"put":{"operationId":"updateSubscriptionCheckout","summary":"Update checkout basket to update subscription","tags":["Legacy"],"description":"**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.\n\nUpdate existing basket with order items (add/remove offers and add-ons).\n\n**Business Logic:**\n- Only 1 add offer allowed per request\n- System auto-adds remove action for current subscription offer when adding new offer\n- System auto-removes incompatible add-ons when switching subscription offers\n- System calculates prices, line items, and effective dates\n- Cross-sells are recalculated based on updated basket\n\n**Requirements:**\n- basketId must be present in landing state cookie (from POST response)\n- Basket must belong to authenticated user\n","parameters":[{"name":"X-Limio-Recaptcha","in":"header","required":true,"schema":{"type":"string"},"description":"reCAPTCHA token for bot prevention"},{"name":"Cookie","in":"header","required":true,"schema":{"type":"string"},"description":"Landing state cookie containing basketId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionCheckoutRequest"}}}},"responses":{"200":{"description":"Basket updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCheckoutResponse"}}}},"400":{"description":"Invalid request or multiple add offers provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Basket not found in landing state","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.limio.com/api/checkout-baskets-api/legacy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.