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

put

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.

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>

Header parameters

CookiestringRequired

Landing state cookie containing the basketId.

Body

application/json

Responses

200

Basket updated successfully.

application/json

idstringRequired

The basket ID.

orderobjectRequired

The updated order.

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.

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/update

HTTPcURLJavaScriptPython

PUT /api/checkout/update HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Cookie: text
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "orderActions": [
    {
      "orderItemActionType": "add",
      "offerId": "text",
      "orderItemId": "text",
      "quantity": 1,
      "version": "text",
      "parentId": "text"
    }
  ]
}

{
  "id": "text",
  "order": {},
  "orderActionResults": [
    {
      "id": "text",
      "actionType": "add"
    }
  ]
}

Retrieve existing checkout basket to update subscription

get

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.

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-07-20T04:03:12.200Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-07-20T04:03:12.200Z",
    "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"
  }
}

Create checkout basket to update subscription

post

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)

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-07-20T04:03:12.200Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-07-20T04:03:12.200Z",
    "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 checkout basket to update subscription

put

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

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-07-20T04:03:12.200Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-07-20T04:03:12.200Z",
    "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"
  }
}