> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/api/checkout-baskets-api/new-subscription.md).
# 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
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Limio Commerce API","version":"1.0.0"},"tags":[{"name":"New Subscription","description":"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."}],"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 `"}},"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 basket for new subscription","tags":["New Subscription"],"description":"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.\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.\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":"Checkout basket 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"}}}}}}
```
## Apply promo code to checkout 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":"New Subscription","description":"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."}],"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 `"}},"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 checkout basket","tags":["New Subscription"],"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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.limio.com/api/checkout-baskets-api/new-subscription.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.