Checkout & Baskets

Create, update, and retrieve checkout baskets. Includes the initiate-checkout flow and abandoned basket retrieval for remarketing purposes.

Get Abandoned Baskets

get

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.

You can use the Abandoned Baskets API for actions such as:

• Obtaining marketing information on customers who have abandoned their checkout.

• Gathering information that can be used to remarket to abandoned checkout customers.

• Understanding customer behaviour.

• Tracking abandoned checkouts over time.

• Viewing abandoned checkout items.

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Query parameters

limitintegerRequired

Maximum number of objects to return. Defaults to 50 if not specified.

Default: 50Example: 10

createdAfterstring · date-timeRequired

Filter items created after the provided ISO date-time string

Example: 2020-12-01T16:00:00Z

queryMorestringOptional

Retrieves the next page of results. Use the queryMore returned in the previous response.

Example: DnF1ZXJ5VGhlbkZldGNoBQAAAAAAGH

Responses

200

OK

application/json

queryMorestringOptional

Cursor for the next page of results

Example: eyJ2IjoiMSIsImMiOiJjYjY0ZDY1YS1iYzQwLTQ3YjItODI5Ny1mN2E4ZGEyYjA0M2UiLCJyIjoiMjAyNC0wMy0yNlQxNTowNDo1NC45NzVaIn0=

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

502

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.

application/json

get

/checkout/abandoned

HTTPcURLJavaScriptPython

GET /api/checkout/abandoned?limit=10&createdAfter=2020-12-01T16%3A00%3A00Z HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364",
      "created": "2024-03-26T15:44:54.975Z",
      "customerDetails": {
        "email": "[email protected]"
      },
      "orderItems": [
        {
          "name": "The Offer",
          "path": "/offers2/The Offer",
          "products": [
            {
              "path": "/products/Digital All Access",
              "productCode": "SKU-00000001"
            }
          ]
        }
      ],
      "tracking": {},
      "identities": [
        {
          "sub": "[email protected]",
          "iss": "https://issuer.domain",
          "service": "salesforce",
          "type": "account"
        }
      ],
      "entry": "/checkout",
      "completed": false,
      "recoveryLink": "/api/checkout/recover?basket=basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364&recover=abc123"
    }
  ],
  "queryMore": "eyJ2IjoiMSIsImMiOiJjYjY0ZDY1YS1iYzQwLTQ3YjItODI5Ny1mN2E4ZGEyYjA0M2UiLCJyIjoiMjAyNC0wMy0yNlQxNTowNDo1NC45NzVaIn0="
}

Create or Update Checkout Session

post

Create or update a basket in Limio for tracking through the checkout flow. This is the first step in the checkout process — the basket captures the customer's selected offers, pricing, and configuration before order submission. If a basket already exists for the session, it will be updated with the new data. The basket ID is returned in the response for use in subsequent checkout and order submission calls.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Body

application/json

Create a new basket

Responses

200

Basket created or updated successfully.

application/json

idstringOptional

The unique ID of the created or updated basket.

Example: basket-a1b2c3d4e5f6

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

502

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.

application/json

post

/checkout/initiate

HTTPcURLJavaScriptPython

POST /api/checkout/initiate HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 440

{
  "order": {
    "orderItems": [
      {
        "offer": {
          "id": "8a512ee55befaea0f7fa962cea9982d0e84f0098",
          "version": "4dd34671f26fdbbf240560b78f7f2f54654cde72"
        },
        "quantity": 1
      }
    ],
    "external_id": "1234567890",
    "tracking": {
      "offers": [
        "/offers2/$75 for 52 weeks then $31.96 every 4 weeks autorenew"
      ],
      "purchaseCountryCode": "GB",
      "accountId": "0017x00000Q9O9qAAF",
      "contactId": "0037x00000F58M9AAJ",
      "userId": "0057x0000088Oh3AAE"
    },
    "country": "GB",
    "source": "shop",
    "order_type": "new"
  }
}

{
  "id": "basket-a1b2c3d4e5f6"
}

Retrieve existing subscription checkout basket

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Header parameters

CookiestringRequired

Landing state cookie containing basketId

Responses

200

Basket retrieved successfully

application/json

completedbooleanOptional

Whether the checkout is completed

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

No basket found in landing state

application/json

502

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.

application/json

get

/checkout/subscription

HTTPcURLJavaScriptPython

GET /api/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Cookie: text
Accept: */*

{
  "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-03-13T12:21:19.308Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:21:19.308Z",
    "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,
  "context": {
    "client_ip": "text",
    "requestId": "text",
    "identity_id": "text"
  },
  "journey": {
    "referrer": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Initiate update subscription checkout

post

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)

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Header parameters

X-Limio-RecaptchastringRequired

reCAPTCHA token for bot prevention

X-Forwarded-ForstringOptional

Client IP address

RefererstringOptional

Referrer URL for journey tracking

Body

application/json

trackingobjectOptional

Optional tracking data for analytics and reporting

Responses

200

Checkout basket created successfully

application/json

400

Invalid request body or missing required fields

application/json

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

Subscription not found

application/json

423

Subscription has pending change, checkout locked

application/json

502

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.

application/json

post

/checkout/subscription

HTTPcURLJavaScriptPython

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"
  }
}

Basic subscription checkout initiationInitiate by subscription nameWith tracking and external IDPre-select target offer

{
  "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-03-13T12:21:19.308Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:21:19.308Z",
    "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,
  "context": {
    "client_ip": "text",
    "requestId": "text",
    "identity_id": "text"
  },
  "journey": {
    "referrer": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update subscription checkout basket

put

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

Authorizations

bearerAuth

AuthorizationstringRequired

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>

Header parameters

X-Limio-RecaptchastringRequired

reCAPTCHA token for bot prevention

CookiestringRequired

Landing state cookie containing basketId

Body

application/json

Responses

200

Basket updated successfully

application/json

completedbooleanOptional

Whether the checkout is completed

400

Invalid request or multiple add offers provided

application/json

401

Unauthorized — the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.

application/json

404

Basket not found in landing state

application/json

502

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.

application/json

put

/checkout/subscription

HTTPcURLJavaScriptPython

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
      }
    ]
  }
}

Upgrade to premium subscriptionAdd subscription add-onAdd multiple add-ons

{
  "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-03-13T12:21:19.308Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:21:19.308Z",
    "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,
  "context": {
    "client_ip": "text",
    "requestId": "text",
    "identity_id": "text"
  },
  "journey": {
    "referrer": "text",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}