Partner Subscription Checkout

APIs for partners to manage subscription checkout flows

Retrieve existing subscription update checkout basket (Partner)

get

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

Requires partner authentication.

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

/partner/checkout/subscription

HTTPcURLJavaScriptPython

GET /api/partner/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:37:18.765Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:37:18.765Z",
    "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 subscription update checkout (Partner)

post

Partner endpoint to create a new basket for subscription updates 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)

Requires partner authentication.

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

xLimioRecaptchastringRequired

reCAPTCHA token for bot prevention

xForwardedForstringOptional

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

/partner/checkout/subscription

HTTPcURLJavaScriptPython

POST /api/partner/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
xLimioRecaptcha: 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:37:18.765Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:37:18.765Z",
    "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 (Partner)

put

Partner endpoint to 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 be accessible by partner

Requires partner authentication.

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

xLimioRecaptchastringRequired

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

/partner/checkout/subscription

HTTPcURLJavaScriptPython

PUT /api/partner/checkout/subscription HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
xLimioRecaptcha: 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:37:18.765Z"
      }
    ],
    "country": "US",
    "source": "shop",
    "effectiveDate": "2026-03-13T12:37:18.765Z",
    "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"
  }
}