Guide: Initiate a Basket with a Limio Offer

Overview

Purchase Links and standard Offers Pages are great for communicating acquisition journeys where every visitor sees the same public offer.

For win-back, renewal, upsell and other targeted flows, you usually want more control because you already know who the customer is. You might want to send them straight to checkout from an email, your CRM, or your own app instead of dropping them on to a landing page to choose an Offer.

In those cases, you can create a service using Limio APIs that will create and pre-populate a Limio basket for that specific customer before they ever click through. For example, you can:

• Decide if they’re eligible for a specific price or offer
• Prefill known details (email, account ID, address) so they don’t have to type them
• Add extra metadata to the Limio basket (cart) that only exists in your system, like campaign codes or CRM IDs

This gives you a few advantages:

• No pricing/eligibility logic in the browser. All rules stay on your side, not in public JavaScript.
• Cleaner handoff into checkout. The basket is already built, so the customer lands in a ready to pay state with minimal clicks.
• Richer basket data. You can attach custom fields and tracking info up front, instead of trying to stitch it together later.

Prerequisites

• Access to the Limio Commerce API with a valid Bearer token carrying the admin scope. All requests in this guide use Authorization: Bearer <YOUR_TOKEN>.
• A published Offer configured in Limio. If you’re new to Offers, start here: What are Offers and how to configure them?
• (Optional but recommended) One or more Custom Attributes on your Offer to help you query the right Offer for a campaign or journey. Learn how to add attributes to templates here.
• Limio Shop page with Modular Checkout (Form) to complete the order. See the Limio SDK Basket page for how the cart/basket is used in components.

What you’ll build

1. Fetch Offers (V2) and optionally filter by a custom attribute (e.g., a campaign code) to locate the exact Offer and Version you want.
2. Create a checkout basket with that Offer’s id and version. The API returns the basket id and a recovery link.
3. Send the shopper to checkout using that recovery link, so they land on a ready-to-pay checkout with the Offer already in the basket.

This guide uses the Create checkout basket for new subscription API (POST /api/admin/checkout/initiate). It is the server-to-server endpoint: it authenticates with a bearer token, so it can be called from your backend, your CRM, or a scheduled job.

Do not use the shop’s own /api/checkout/initiate for this. That endpoint is for the browser: it relies on the shopper’s session cookie, which your backend does not have.

Fetch your Offers

Use Get Offers V2 to retrieve standalone Offers. You can retrieve all your offers or use the attributes parameter to fetch only the Offers relevant to your campaign. The attribute is a custom attribute that you define in your Offer template (e.g., campaign_code=WIN001). Note that the __limio suffix is reserved for Limio's own attributes, so do not use it when naming your own.

Example — fetch offers with a campaign attribute (curl)

curl -s -G \
  'https://your-environment.prod.limio.com/api/offers/v2' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-urlencode 'attributes.campaign_code=WIN001' \
  --data-urlencode 'reducedData=true' \
  --data-urlencode 'offersSource=published' \
  --data-urlencode 'opt.pageSize=10'

Notes:

• attributes.<YOUR_ATTRIBUTE> limits results to Offers that have this specific attribute value
• offersSource=published limits results to published Offers; use catalog to return all from your catalog.
• reducedData=true makes responses smaller when you only need keys like id, version, path, etc.

Response (truncated):

{
  "hits": 1,
  "items": [
    {
      "id": "fab052ce94fbfd0d3663ec0cb9d977367a593684",
      "name": "Offer Digital",
      "path": "/offers2/Offer Digital",
      "version": "101d166f7386bb9f1c7635412424b51bbe393ccc",
      "record_type": "offer"
    }
  ]
}

If you’re unfamiliar with configuring Offers and their attributes, see the Offers overview and Templates & Custom Attributes docs.

Create the basket with your Offer

Use Create checkout basket for new subscription to create a Limio basket that includes your chosen Offer. These fields are required:

• order.orderItems[].offer — the Offer id and version you fetched in Step 1
• order.external_id — your external reference. It becomes the checkoutId of the order, so use something you can trace back to your system
• order.country, order.source, order.order_type ("new" here)

And these are optional:

• order.tracking — analytics and CRM metadata (offers, purchaseCountryCode, Salesforce IDs). Passing tracking.accountId also assigns the basket an owner, which changes how you send the customer to checkout — see below
• journey.checkout — send the customer to a custom checkout page instead of the default
• expiresAfter — how long the basket stays alive. Defaults to 14 days
• To apply a promo code, create the basket first, then call POST /api/admin/v2/promo_code with the basketId from the response

Example — create a checkout basket (curl)

curl -s -X POST \
  'https://your-environment.prod.limio.com/api/admin/checkout/initiate' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "order": {
      "orderItems": [
        {
          "offer": {
            "id": "fab052ce94fbfd0d3663ec0cb9d977367a593684",
            "version": "101d166f7386bb9f1c7635412424b51bbe393ccc"
          },
          "quantity": 1
        }
      ],
      "external_id": "WINBACK-2025-000123",
      "tracking": {
        "offers": ["/offers2/Offer Digital"],
        "purchaseCountryCode": "GB",
        "accountId": "0017x00000Q9O9qAAF",
        "contactId": "0037x00000F58M9AAJ",
        "userId": "0057x0000088Oh3AAE"
      },
      "country": "GB",
      "source": "shop",
      "order_type": "new"
    },
    "expiresAfter": { "days": 7 }
  }'

Response:

{
  "id": "basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364",
  "recoveryLink": "/api/checkout/recover?basketId=basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364&recover=eyJ...",
  "assistedCheckoutLink": "/api/checkout/assisted?basketId=basket-8cf72b2a-eb57-462d-8e55-981c3b5e5364&cl=eyJ...",
  "order": {
    "orderItems": [ /* verified items with resolved pricing */ ],
    "total": { "currency": "GBP", "amount": 99.0 },
    "orderVersion": "a1b2c3..."
  }
}

• recoveryLink — a signed URL, valid 30 days. This is how you send the customer to checkout.
• assistedCheckoutLink — returned only when you passed tracking.accountId. The example above does, so it gets one.
• order — the order as Limio resolved it, with real pricing. Worth logging: this is the source of truth, not what you sent.

Send the customer to checkout

Send them to the recoveryLink, appended to your shop domain:

https://your-environment-shop.prod.limio.com/api/checkout/recover?basketId=basket-8cf72b2a...&recover=eyJ...

That link does two things a bare basket id cannot: it establishes the shopper’s checkout session in their browser, then redirects them to the checkout page with the basket loaded.

Do not build your own ?basket=<id> URL. Your backend created this basket, so the shopper’s browser has no session for it, and a basket id alone does not create one. The signed recovery link is what carries the session across.

If you passed tracking.accountId, use the assistedCheckoutLink instead. It does the same thing, but also signs the customer in on behalf of that account (an OBO flow), so an agent or a CRM-driven journey lands them straight into an authenticated checkout.

Once they arrive, your checkout page renders the basket as normal. Use the Limio SDK Basket helpers in your components to read the cart and any custom fields you attached.

For checkout UI, see Component: Form (Modular Checkout) and related guidance on composing a checkout page with subcomponents.

End-to-end example (Node.js)

Below is a minimal Node.js service that finds an Offer by attribute, creates a basket, and returns a link you can drop into an email or your CRM.

import express from "express";

const app = express();
app.use(express.json());

const LIMIO_BASE = "https://your-environment.prod.limio.com";
const SHOP_BASE = "https://your-environment-shop.prod.limio.com";
const TOKEN = process.env.LIMIO_TOKEN;

// Find an Offer by custom attribute and create a checkout basket for it
app.post("/winback", async (req, res) => {
  const { campaignCode, externalId, country = "GB", accountId } = req.body;

  // 1) Get Offers V2 filtered by attribute
  const offersUrl = new URL(`${LIMIO_BASE}/api/offers/v2`);
  offersUrl.searchParams.set(`attributes.campaign_code`, campaignCode);
  offersUrl.searchParams.set("offersSource", "published");
  offersUrl.searchParams.set("reducedData", "true");

  const offersResp = await fetch(offersUrl, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  if (!offersResp.ok) {
    return res.status(offersResp.status).send(await offersResp.text());
  }
  const offers = await offersResp.json();
  const offer = offers.items?.[0];
  if (!offer) return res.status(404).send("Offer not found");

  // 2) Create the basket with the Offer id + version
  const initiateResp = await fetch(`${LIMIO_BASE}/api/admin/checkout/initiate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      order: {
        orderItems: [{ offer: { id: offer.id, version: offer.version }, quantity: 1 }],
        external_id: externalId, // becomes the checkoutId of the order
        tracking: {
          offers: [offer.path],
          purchaseCountryCode: country,
          // Passing accountId assigns the basket an owner and returns an
          // assistedCheckoutLink, which signs the customer in on their behalf.
          ...(accountId && { accountId }),
        },
        country,
        source: "shop",
        order_type: "new",
      },
      expiresAfter: { days: 7 },
    }),
  });

  if (!initiateResp.ok) {
    return res.status(initiateResp.status).send(await initiateResp.text());
  }
  const { id: basketId, recoveryLink, assistedCheckoutLink } = await initiateResp.json();

  // 3) Build the link to send the customer. Both establish their checkout
  //    session and redirect them into checkout with the basket loaded.
  const checkoutUrl = `${SHOP_BASE}${assistedCheckoutLink ?? recoveryLink}`;
  res.json({ basketId, checkoutUrl });
});

app.listen(3000);

Tips & troubleshooting

• Why not just pass the basket id to my checkout page? Because your backend created the basket, the shopper’s browser has no session for it. The recoveryLink establishes that session and then redirects; a bare id does not.
• How long does the link last? The signed token in recoveryLink and assistedCheckoutLink is valid for 30 days. The basket itself expires after 14 days unless you set expiresAfter.
• Can I page through lots of Offers? Yes — use opt.all=true and follow queryMore pointers (from + alias) to retrieve subsequent pages.
• Published vs catalog: If your org uses Published Offers, set offersSource=published to restrict results to published records.
• Basket anatomy: To understand what’s inside a basket and how your shop components read it, review the Basket SDK page.
• Abandoned baskets: If you’re running remarketing flows, see the Abandoned Baskets API for retrieving in-progress but uncompleted baskets. It returns a recoveryLink for each one, the same mechanism this guide uses.
• Renewals: To build a basket for an existing subscription’s renewal rather than a new purchase, use Create checkout basket to renew subscription.