# Checkout & Baskets

Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets.

## Update Checkout Basket

> 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":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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 Checkout Basket","tags":["Checkout & Baskets"],"description":"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.","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"}}}}}}
```

## Get Abandoned Baskets

> This API allows you to get a list of abandoned baskets in Limio and filter the results by the date the basket was created.\
> An abandoned basket is one where a basket was started on the Limio checkout but the order was never completed.\
> &#x20;   \
> You can use the Abandoned Baskets API for actions such as:\
> \
> &#x20; \- Obtaining marketing information on customers who have abandoned their checkout.\
> &#x20; \- Gathering information that can be used to remarket to abandoned checkout customers.\
> &#x20; \- Understanding customer behaviour.\
> &#x20; \- Tracking abandoned checkouts over time.\
> &#x20; \- Viewing abandoned checkout items.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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>`"}},"parameters":{"limit":{"in":"query","name":"limit","description":"Maximum number of objects to return. Defaults to 50 if not specified.","schema":{"type":"integer","default":50}},"createdAfter":{"in":"query","name":"createdAfter","description":"Filter items created after the provided ISO date-time string","schema":{"type":"string","format":"date-time"}},"queryMore":{"in":"query","name":"queryMore","description":"Retrieves the next page of results. Use the queryMore returned in the previous response.","schema":{"type":"string"}}},"schemas":{"GetAbandonedCheckoutsResponse":{"type":"object","properties":{"items":{"type":"array","description":"The list of baskets retrieved","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the basket"},"created":{"type":"string","format":"date-time","description":"The date and time the basket was created"},"customerDetails":{"type":"object","description":"Details about the customer or potential customer that abandoned the checkout","properties":{"email":{"type":"string","description":"The value from the checkout form email field, or the user's email if they authenticated"},"firstName":{"type":"string","description":"Customer's first name"},"lastName":{"type":"string","description":"Customer's last name"},"companyName":{"type":"string","description":"Customer's company name"}}},"orderItems":{"type":"array","description":"The list of order items in the basket","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the order item"},"path":{"type":"string","description":"The path of the order item"},"products":{"type":"array","description":"The list of products associated with the order item","items":{"type":"object","properties":{"path":{"type":"string","description":"The path of the product"},"productCode":{"type":"string","description":"The product code"}}}}}}},"customFields":{"type":"object","description":"Custom fields from the order","additionalProperties":true},"tracking":{"type":"object","description":"Tracking data for the basket, including the originating page and tag. The `tag` field can be used to filter baskets by sales channel (e.g. direct, referral, reseller)","properties":{"offers":{"type":"array","description":"List of offer paths being tracked","items":{"type":"string"}},"campaign":{"type":"string","description":"The Limio page path where the checkout was initiated"},"tag":{"type":"string","description":"The tag associated with the checkout entry point, typically reflecting the sales channel"}}},"identities":{"type":"array","description":"The list of identities associated with the basket","items":{"type":"object","properties":{"sub":{"type":"string","description":"The subject identifier"},"iss":{"type":"string","description":"The issuer"},"service":{"type":"string","description":"The service associated with the identity"},"type":{"type":"string","description":"The type of identity"}}}},"entry":{"type":"string","description":"The entry point URL for the basket, including any UTM parameters from the original visit. Useful for preserving campaign attribution in recovery emails"},"completed":{"type":"boolean","description":"Indicates if the basket has been completed"},"recoveryLink":{"type":"string","description":"Recovery link to provide to user to allow them to recover abandoned checkout session"}}}},"queryMore":{"type":"string","description":"Cursor for the next page of results"}}}},"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/abandoned":{"get":{"description":"This API allows you to get a list of abandoned baskets in Limio and filter the results by the date the basket was created.\nAn abandoned basket is one where a basket was started on the Limio checkout but the order was never completed.\n    \nYou can use the Abandoned Baskets API for actions such as:\n\n  - Obtaining marketing information on customers who have abandoned their checkout.\n  - Gathering information that can be used to remarket to abandoned checkout customers.\n  - Understanding customer behaviour.\n  - Tracking abandoned checkouts over time.\n  - Viewing abandoned checkout items.","operationId":"getAbandonedCheckouts","summary":"Get Abandoned Baskets","tags":["Checkout & Baskets"],"parameters":[{"$ref":"#/components/parameters/limit","required":true},{"$ref":"#/components/parameters/createdAfter","required":true},{"$ref":"#/components/parameters/queryMore"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAbandonedCheckoutsResponse"}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Retrieve existing subscription checkout basket

> Fetch existing basket by basketId from landing state cookie. Used to retrieve current checkout state after page refresh or navigation.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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 subscription checkout basket","tags":["Checkout & Baskets"],"description":"Fetch existing basket by basketId from landing state cookie. Used to retrieve current checkout state after page refresh or navigation.","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"}}}}}}
```

## Initiate update subscription checkout

> 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:\*\*\
> \- Checkout & Baskets 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":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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":"Initiate update subscription checkout","tags":["Checkout & Baskets"],"description":"Create 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- Checkout & Baskets 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 subscription checkout basket

> 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)\
> \- Checkout & Baskets must belong to authenticated user<br>

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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 subscription checkout basket","tags":["Checkout & Baskets"],"description":"Update 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- Checkout & Baskets 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"}}}}}}
```

## Create Checkout Session

> Create a basket in Limio. This endpoint is used to programmatically create checkout sessions, typically for integrations, purchase links, or customer service workflows.\
> \
> \*\*Offers and add-ons:\*\* Include offers and add-ons directly in \`orderItems\`. Use \`type: "offer"\` for offers and \`type: "add\_on"\` for add-ons. Retrieve \`id\` and \`version\` for each item from \`GET /offers/v2\` (offers) or \`GET /add\_ons\` (add-ons).\
> \
> \*\*Recovery link:\*\* The response includes a \`recoveryLink\` — a signed URL (valid 30 days) that can be sent to customers to resume the checkout session.\
> \
> \*\*Assisted checkout:\*\* When \`tracking.accountId\` is provided, the response also includes an \`assistedCheckoutLink\` which enables OBO (On-Behalf-Of) token flow for Salesforce-initiated checkouts.\
> \
> \*\*Promo codes:\*\* To apply a promo code, first create the basket using this endpoint, then call \`POST /admin/v2/promo\_code\` with the \`basketId\` from the response and the promo code.<br>

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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":["admin"]}],"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":{"admin_InitiateCheckout":{"type":"object","title":"Initiate Checkout","description":"Create a new checkout session. Extends the standard initiate checkout request with additional fields such as journey configuration and flexible basket expiry.","allOf":[{"$ref":"#/components/schemas/InitiateCheckout"},{"type":"object","properties":{"journey":{"type":"object","description":"Optional journey configuration for the checkout session. Allows specifying a custom checkout URL for the customer.","properties":{"checkout":{"type":"string","description":"Custom checkout page path for the customer to complete the order."}}},"expiresAfter":{"type":"object","description":"How long the basket should remain active before expiring. Defaults to 14 days if not specified.","properties":{"seconds":{"type":"integer","minimum":60,"description":"Expiry in seconds (min 60)."},"minutes":{"type":"integer","minimum":1,"description":"Expiry in minutes."},"hours":{"type":"integer","minimum":1,"description":"Expiry in hours."},"days":{"type":"integer","minimum":1,"description":"Expiry in days."}}}}}]},"InitiateCheckout":{"type":"object","title":"Initiate Checkout","description":"Create a new basket","allOf":[{"type":"object","properties":{"order":{"type":"object","properties":{"orderItems":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferPayload"},"quantity":{"type":"number"},"type":{"type":"string","description":"Item type. Only required when the basket includes add-ons alongside offers — set to \"offer\" for the main offer and \"add_on\" for each add-on. Can be omitted for offer-only baskets.","enum":["offer","add_on"]}}}},"external_id":{"type":"string","description":"external order reference - becomes the checkoutId of the order"},"tracking":{"$ref":"#/components/schemas/Tracking"},"country":{"type":"string","description":"the country code of the customer's purchase location"},"source":{"type":"string","description":"source of the order"},"order_type":{"type":"string","enum":["new","renew"]}},"required":["orderItems","external_id","country","source","order_type"]}},"required":["order"]}]},"OfferPayload":{"description":"Reference to a published Limio offer.\nRetrieve `id` and `version` from `GET /offers/v2`.\n","required":["id","version"],"properties":{"id":{"type":"string","description":"The unique content hash of the offer. Retrieve from `GET /offers/v2`."},"version":{"type":"string","description":"The version hash of the offer. Use the latest version from the same API response."}}},"Tracking":{"type":"object","description":"Tracking data associated with the order, used for attribution and integration with external systems. When `accountId` is provided, the basket is assigned an owner and the response includes an `assistedCheckoutLink` for OBO (On-Behalf-Of) checkout flows.","properties":{"offers":{"type":"array","items":{"type":"string"}},"purchaseCountryCode":{"type":"string"},"accountId":{"type":"string","description":"Salesforce Account ID. When provided, Limio resolves or creates an identity owner for the basket and returns an `assistedCheckoutLink` in the response."},"contactId":{"type":"string","description":"Salesforce Contact ID associated with this order."},"userId":{"type":"string","description":"Salesforce User ID associated with this order."}}}},"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":{"/admin/checkout/initiate":{"post":{"operationId":"admin_initiateCheckout","summary":"Create Checkout Session","tags":["Checkout & Baskets"],"description":"Create a basket in Limio. This endpoint is used to programmatically create checkout sessions, typically for integrations, purchase links, or customer service workflows.\n\n**Offers and add-ons:** Include offers and add-ons directly in `orderItems`. Use `type: \"offer\"` for offers and `type: \"add_on\"` for add-ons. Retrieve `id` and `version` for each item from `GET /offers/v2` (offers) or `GET /add_ons` (add-ons).\n\n**Recovery link:** The response includes a `recoveryLink` — a signed URL (valid 30 days) that can be sent to customers to resume the checkout session.\n\n**Assisted checkout:** When `tracking.accountId` is provided, the response also includes an `assistedCheckoutLink` which enables OBO (On-Behalf-Of) token flow for Salesforce-initiated checkouts.\n\n**Promo codes:** To apply a promo code, first create the basket using this endpoint, then call `POST /admin/v2/promo_code` with the `basketId` from the response and the promo code.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/admin_InitiateCheckout"}}}},"responses":{"200":{"description":"Admin checkout session created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","recoveryLink","order"],"properties":{"id":{"type":"string","description":"The unique ID of the created basket."},"recoveryLink":{"type":"string","description":"URL path for the customer to recover and resume this checkout session. Includes a signed token valid for 30 days."},"assistedCheckoutLink":{"type":"string","description":"URL path for assisted checkout (on-behalf-of flow). Only returned when `tracking.accountId` is provided in the request, which resolves or creates a basket owner. The signed token is valid for 30 days."},"order":{"type":"object","description":"The verified order data with resolved pricing and upsells.","properties":{"orderItems":{"type":"array","description":"The verified order items with resolved offer details.","items":{"type":"object"}},"total":{"type":"object","description":"Calculated order totals."},"orderVersion":{"type":"string","description":"Hash of the order used for optimistic concurrency."}}}}}}}},"401":{"$ref":"#/components/responses/401Response"},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Create Renewal Checkout Session

> Create a checkout session for renewing an existing subscription. Looks up the subscription by ID or reference, retrieves the customer's renewal details, and creates a basket pre-populated with the renewal context.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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":["admin"]}],"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":{"/admin/checkout/initiate/renew":{"post":{"operationId":"admin_initiateRenewCheckout","summary":"Create Renewal Checkout Session","tags":["Checkout & Baskets"],"description":"Create a checkout session for renewing an existing subscription. Looks up the subscription by ID or reference, retrieves the customer's renewal details, and creates a basket pre-populated with the renewal context.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order"],"properties":{"order":{"type":"object","properties":{"external_id":{"type":"string","description":"External order reference."},"subId":{"type":"string","description":"The Limio subscription ID to renew."},"subRef":{"type":"string","description":"The external subscription reference to renew."},"order_type":{"type":"string","enum":["renew"],"default":"renew"},"verify":{"type":"object","description":"Customer details to verify against the subscription.","properties":{"customerDetails":{"type":"object","properties":{"email":{"type":"string","format":"email"}}},"address":{"type":"object"}}}}},"expiresAfter":{"type":"object","description":"How long the basket should remain active.","properties":{"seconds":{"type":"integer","minimum":60},"minutes":{"type":"integer","minimum":1},"hours":{"type":"integer","minimum":1},"days":{"type":"integer","minimum":1}}}}}}}},"responses":{"200":{"description":"Renewal checkout session created successfully.","content":{"application/json":{"schema":{"type":"object","required":["id","order"],"properties":{"id":{"type":"string","description":"The unique ID of the created renewal basket."},"segments":{"type":"array","description":"Customer segments applicable to the renewal.","items":{"type":"string"}},"order":{"type":"object","description":"The pre-populated renewal order details.","properties":{"external_id":{"type":"string"},"order_type":{"type":"string"},"subId":{"type":"string"},"subRef":{"type":"string"},"customerDetails":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"}}},"country":{"type":"string"},"renewalDetails":{"type":"object","description":"Details of the subscription being renewed.","properties":{"subscription":{"type":"object"},"attributes":{"type":"object"}}},"tracking":{"type":"object"},"hideEmailField":{"type":"boolean"},"hidePriceField":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Subscription not found for renewal."},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```

## Apply Promo Code to Basket

> Apply a promotional code to an existing checkout basket. Validates the code, applies applicable discounts, and returns the updated order with recalculated pricing.

```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"Checkout & Baskets","description":"Create, update, and retrieve checkout baskets. Includes initiating checkout sessions, renewal checkouts, applying promo codes, updating baskets, and retrieving abandoned baskets."}],"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":["admin"]}],"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":{"/admin/v2/promo_code":{"post":{"operationId":"admin_addPromoCodeToBasket","summary":"Apply Promo Code to Basket","tags":["Checkout & Baskets"],"description":"Apply a promotional code to an existing checkout basket. Validates the code, applies applicable discounts, and returns the updated order with recalculated pricing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","basketId"],"properties":{"code":{"type":"string","description":"The promotional code to apply."},"basketId":{"type":"string","description":"The basket ID to apply the promo code to."}}}}}},"responses":{"200":{"description":"Promo code applied successfully.","content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The basket ID."},"order":{"type":"object","description":"The updated order with discount applied.","properties":{"orderItems":{"type":"array","items":{"type":"object"}},"orderDiscount":{"type":"object","description":"The applied discount details."},"total":{"type":"object","description":"Recalculated order totals."},"orderVersion":{"type":"string","description":"Updated order version hash."}}}}}}}},"400":{"description":"Invalid or expired promo code."},"401":{"$ref":"#/components/responses/401Response"},"404":{"description":"Basket not found."},"502":{"$ref":"#/components/responses/502Response"}}}}}}
```