New Subscription

Create checkout baskets for new subscription purchases and apply promo codes to them. Baskets are created with an OAuth Bearer token and return a recovery link the customer can use to complete checkout.

Create checkout basket for new subscription

post

Create a checkout basket in Limio for a new subscription purchase. This endpoint is used to programmatically create checkout baskets, 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.

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.

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

Checkout basket created successfully.

application/json

idstringRequired

The unique ID of the created basket.

Example: basket-a1b2c3d4e5f6

recoveryLinkstringRequired

URL path for the customer to recover and resume this checkout session. Includes a signed token valid for 30 days.

Example: /api/checkout/recover?basketId=basket-a1b2c3d4e5f6&recover=eyJ...

assistedCheckoutLinkstringOptional

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.

Example: /api/checkout/assisted?basketId=basket-a1b2c3d4e5f6&cl=eyJ...

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/admin/checkout/initiate

HTTPcURLJavaScriptPython

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

{
  "order": {
    "orderItems": [
      {
        "offer": {
          "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
          "version": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5"
        },
        "quantity": 1
      }
    ],
    "external_id": "order-001",
    "country": "US",
    "source": "shop",
    "order_type": "new"
  }
}

Single offerOffer with add-onWith Salesforce tracking and custom journey

{
  "id": "basket-a1b2c3d4e5f6",
  "recoveryLink": "/api/checkout/recover?basketId=basket-a1b2c3d4e5f6&recover=eyJ...",
  "assistedCheckoutLink": "/api/checkout/assisted?basketId=basket-a1b2c3d4e5f6&cl=eyJ...",
  "order": {
    "orderItems": [
      {}
    ],
    "total": {},
    "orderVersion": "text"
  }
}

Apply promo code to checkout basket

post

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

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

codestringRequired

The promotional code to apply.

Example: SUMMER20

basketIdstringRequired

The basket ID to apply the promo code to.

Example: basket-a1b2c3d4e5f6

Responses

200

Promo code applied successfully.

application/json

idstringRequired

The basket ID.

400

Invalid or expired promo code.

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.

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/admin/v2/promo_code

HTTPcURLJavaScriptPython

POST /api/admin/v2/promo_code HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "code": "SUMMER20",
  "basketId": "basket-a1b2c3d4e5f6"
}

{
  "id": "text",
  "order": {
    "orderItems": [
      {}
    ],
    "orderDiscount": {},
    "total": {},
    "orderVersion": "text"
  }
}