Guide: Enable commerce for first-party AI agents

How to connect an AI agent (Agentforce, Qualified, or custom) to Limio so it can sell subscriptions and create quotes.

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 and the code is 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.

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.

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.

Prerequisites

• OAuth client credentials (client_id and client_secret) from Limio Support
• 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:

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:

{
  "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.

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:

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, such as 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 https://app.gitbook.com/s/5Gy03wYWGmfZvpUzhsiY/checkout-api/checkout-and-baskets#post-admin-checkout-initiate.

Step 3: Create the checkout session

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

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": "[e-mail]",
        "company": "Acme Corp"
      }
    },
    "journey": {
      "checkout": "/checkout"
    },
    "expiresAfter": {
      "days": 14
    }
  }'

Response:

{
  "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.

The recoveryLink is a signed URL. Return it exactly as the API provides it. Do not modify or reconstruct it.

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 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.

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: the 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 recommend offers dynamically, use the Offers V2 API to query by attributes like product group, pricing tier, or custom labels.
• 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.