# Enabling commerce

Your AI agent can sell subscriptions through Limio without building a custom storefront. There are two approaches depending on how much control the agent needs:

* **Purchase links** — the agent constructs a URL and sends the customer to a Limio checkout. No API, no authentication.
* **Assisted checkout via API** — the agent creates a checkout session server-side, pre-fills customer details, and returns a checkout link. Requires an OAuth bearer token.

## Purchase links (no API required)

A purchase link is a URL that sends a customer directly to a Limio checkout page with one or more offers pre-loaded in the basket. The agent just needs to know the shop domain, the checkout page path, and the offer path.

### URL format

```
https://{shop-domain}/{checkout-page}?purchase={url-encoded-offer-path}
```

The offer path is the Limio catalog path for the offer, typically `/offers2/{Offer Name}`. URL-encode it — spaces become `%20`, slashes become `%2F`.

**Single offer:**

```
https://shop.example.com/checkout?purchase=%2Foffers2%2FPro%20Plan
```

**Multiple offers:**

```
https://shop.example.com/checkout?purchase=%2Foffers2%2FPro%20Plan&purchase=%2Foffers2%2FAdd-On
```

**With a promo code:**

```
https://shop.example.com/checkout?purchase=%2Foffers2%2FPro%20Plan&pc=SAVE20
```

If the promo code is invalid or expired, the checkout still loads — the code is silently ignored.

### When to use this

* The agent knows which offer to recommend and just needs to direct the customer to checkout
* No server-side logic, API credentials, or backend infrastructure required
* The agent cannot pre-fill customer details — the customer enters them at checkout

For full details on purchase link options (label-based selection, basket IDs), see [Purchase Links](https://docs.limio.com/product/checkout/how-to-configure-purchase-links).

## Assisted checkout via API

The agent creates a checkout session (basket) server-side with the customer's details pre-filled, then returns a checkout link. This is useful when the agent collects customer information during conversation and wants to create a ready-to-pay checkout — or a quote the customer can review later.

{% hint style="warning" %}
Your agent platform must support storing API credentials and making outbound HTTP calls. For example, Salesforce Agentforce supports this via Named Credentials and custom actions. Platforms that only support conversational flows without server-side API access (e.g. Qualified) should use purchase links instead.
{% endhint %}

### Prerequisites

* **OAuth client credentials** (`client_id` and `client_secret`) from [Limio Support](mailto:support@limio.com?subject=Request%20for%20Client%20ID%20and%20Client%20Secret)
* A **published offer** in Limio with a known `id` and `version`
* A **checkout page** configured in your Limio shop

### Step 1: Get a bearer token

Request an OAuth token using the client credentials grant:

```bash
curl -s -X POST \
  'https://{tenant}.prod.limio.com/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id={YOUR_CLIENT_ID}' \
  -d 'client_secret={YOUR_CLIENT_SECRET}'
```

Response:

```json
{
  "access_token": "<TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Use the `access_token` value in the `Authorization` header for subsequent requests. Tokens expire after 1 hour.

For full details, see [OAuth Bearer Token](https://docs.limio.com/developer-docs/api-documentation/authentication-overview/oauth-bearer-token).

### Step 2: Fetch offers (optional)

If the agent needs to look up offers dynamically rather than using hard-coded IDs, query the [Offers V2 API](/api/catalog-api/catalog.md#get-offers-v2):

```bash
curl -s -G \
  'https://{tenant}.prod.limio.com/api/offers/v2' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-urlencode 'offersSource=published' \
  --data-urlencode 'reducedData=true'
```

You can filter by custom attributes — for example, `attributes.label__limio=pro` — to narrow results to specific product lines. The response includes the `id` and `version` needed for the next step.

For pagination and advanced filtering, see [Checkout & Baskets](/api/checkout-api/checkout-and-baskets.md#post-admin-checkout-initiate).

### Step 3: Create the checkout session

Call the checkout initiate API with the offer, customer details, and checkout journey:

```bash
curl -s -X POST \
  'https://{tenant}.prod.limio.com/api/admin/checkout/initiate' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "orderItems": [
        {
          "offer": {
            "id": "{offer_id}",
            "version": "{offer_version}"
          },
          "quantity": 1
        }
      ],
      "external_id": "quote-1712764800",
      "country": "US",
      "source": "ai-agent",
      "order_type": "new",
      "customerDetails": {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "company": "Acme Corp"
      }
    },
    "journey": {
      "checkout": "/checkout"
    },
    "expiresAfter": {
      "days": 14
    }
  }'
```

Response:

```json
{
  "id": "basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364",
  "recoveryLink": "/api/checkout/recover?basketId=basket-8cf72b2a...&recover=<JWT>",
  "order": { ... }
}
```

### Step 4: Return the checkout URL

#### Sharing the checkout session with the customer

Build the full URL by combining your shop domain with the `recoveryLink`:

```
https://shop.example.com/api/checkout/recover?basketId=basket-8cf72b2a...&recover=<JWT>
```

Send this link to the customer. When they open it, they land on a checkout page with their details and the selected offer pre-loaded — ready to pay.

{% hint style="info" %}
The `recoveryLink` is a signed URL. Return it exactly as the API provides it — do not modify or reconstruct it.
{% endhint %}

#### Using the checkout session to create a quote

If you want to use this flow to generate a quote, your agent can silently make the API call, which will generate a Limio Basket or Cart in an active state.

You can then poll the [Abandon Basket API](/api/checkout-api/checkout-and-baskets.md#get-checkout-abandoned) to generate Leads, Quotes or custom Objects in your CRM such as Salesforce.

### When to use this

* The agent collects customer details (name, email, company) during conversation and wants to pre-fill checkout
* You want to create quotes with an expiry period
* You need to attach CRM context (Salesforce account/contact IDs) via `order.tracking`
* You want to control which checkout page the customer sees via `journey.checkout`

For the full API reference including tracking parameters and Salesforce account linking, see [Sales-assisted checkout links](https://docs.limio.com/guides/developer-guides/guide-checkout-link).

## Choosing an approach

|                                   | Purchase links | Assisted checkout  |
| --------------------------------- | -------------- | ------------------ |
| API required                      | No             | Yes                |
| Authentication                    | None           | OAuth bearer token |
| Pre-fill customer details         | No             | Yes                |
| Quote with expiry                 | No             | Yes                |
| CRM context (account/contact IDs) | No             | Yes                |
| Promo codes                       | Yes (`&pc=`)   | Via offer config   |
| Multiple offers per checkout      | Yes            | Yes                |
| Agent infrastructure              | None           | Needs HTTP client  |

**Start with purchase links** if the agent just needs to point customers to a checkout. Move to the API approach when you need to pre-fill data, create quotes, or integrate with a CRM.

## Tips

* **Payment methods** — available options (card, invoice, ACH, PayPal, direct debit) are determined by the offer configuration, not by the checkout link.
* **Offer lookup** — if your agent needs to dynamically recommend offers, use the Offers V2 API to query by attributes like product group, pricing tier, or custom labels.&#x20;
* **Token management** — OAuth tokens expire after 1 hour. Cache and refresh them rather than requesting a new token per checkout.
* **Fallback** — if the API is unavailable, fall back to a purchase link so the customer can still check out.


---

# Agent Instructions: 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:

```
GET https://docs.limio.com/ai/first-party-ai-agents/enabling-commerce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.