Using LIP with AI

The fastest path from zero to a correct loyalty integration when you build with coding agents and MCP.

Loyalty Interchange Protocol (LIP) is designed for agent-assisted development. Whether you drive Cursor, Claude Code, Codex, or another coding agent to build a restaurant loyalty integration — or you wire an automation that reacts to loyalty events — the resources on this page take an agent from zero to a correct implementation.

LIP is not an identity provider. Your app or backend-for-frontend (BFF) owns customer sign-in; LIP owns the loyalty ledger. Agents should follow that split unless they are building a provider adapter.

AI resources

Everything an agent needs to reason about LIP correctly — no guessing loyalty semantics from training data.

Agent Skills

Installable, task-specific knowledge for checkout, webhooks, the BFF pattern, SDK usage, and conformance.

MCP server

Official server exposing spec lookups, schema validation, and checkout checklists as tools.

llms.txt index

A compact index of the spec, OpenAPI contract, SDK entry points, and CLI — point your agent here first.

AI prompts

Curated prompts that get enroll, checkout, webhook, and refund flows right on the first pass.

Quick setup

1. Point your agent at llms.txt

   Load the checked-in llms.txt so the agent reads the normative spec before changing behavior.

   @llms.txt
   
2. Install the Agent Skills

   From a clone of the repo, install specialized loyalty knowledge into any skills-aware agent.

   npx skills add .
   
3. Connect the MCP server

   Enable the repo-root mcp.json, or run the published server standalone.

   npx @loyalty-interchange/mcp
   

The llms.txt index

The repo root includes llms.txt, a compact index of the normative spec, OpenAPI contract, SDK entry points, CLI commands, and the files agents should read before changing behavior. Point your agent at it first:

@llms.txt

If your tool supports URL context, prefer the checked-in file in your clone over generated summaries — it stays in sync with the code you are actually building against.

Agent Skills

LIP ships installable Agent Skills in the skills/ directory. They give coding agents specialized knowledge for the checkout lifecycle, webhooks, the BFF pattern, SDK usage, and conformance.

Install all

npx skills add .

npx skills add . --skill lip-checkout

npx skills add alvinjchoi/opensource-loyalty

Skill	When to use
lip	Router — start here
lip-cli	serve, doctor, test, validate
lip-sdk	LipClient, idempotency, errors
lip-checkout	evaluate → reserve → accrue → capture → refund
lip-webhooks	signed CloudEvents, receivers
lip-bff	customer app + backend-for-frontend
lip-conformance	doctor, test, e2e patterns

Works with Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and other agents that support the skills format. See the Skills README for the full catalog.

lip init prints the install command when you bootstrap a new project, so the Skills are one step away from any fresh integration.

MCP server

LIP includes an official MCP server that exposes spec lookups, the llms.txt index, OpenAPI operation lists, schema validation, checkout lifecycle checklists, and SDK snippets — so agents do not guess loyalty semantics from training data.

Cursor: enable the repo-root mcp.json (Settings → MCP).

Manual configuration:

Published package

{
  "mcpServers": {
    "lip": {
      "command": "npx",
      "args": ["@loyalty-interchange/mcp"]
    }
  }
}

{
  "mcpServers": {
    "lip": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/server.ts"]
    }
  }
}

Run it standalone:

Published package

npx @loyalty-interchange/mcp

npm run mcp

MCP tools

Tool	Purpose
lip_index	Return llms.txt
lip_read_doc	Read allowed docs/spec files
lip_list_api_operations	Summarize spec/openapi.yaml
lip_list_schemas	Schema names for validation
lip_validate_json	Validate JSON against a schema
lip_checkout_flow	Checkout + refund lifecycle checklist
lip_sdk_snippet	TypeScript snippet for an operation

In MCP, the client is the LLM application (Cursor, Claude) and the server is the tool provider. LIP’s MCP server supplies docs and validation — it does not hold member data or merchant keys. Runtime loyalty calls still go through your BFF and the HTTP API. To expose live loyalty operations as MCP tools in your product, wrap LipClient in a custom server and keep the merchant key server-side.

CLI

The lip CLI is the primary tool for agents and humans to validate, serve, and test a LIP deployment. Use the published package with npx, or npm run lip from a clone.

Published package

npx @loyalty-interchange/cli init
npx @loyalty-interchange/cli serve --api-key lip-dev-key
npx @loyalty-interchange/cli doctor http://127.0.0.1:3210 --api-key lip-dev-key
npx @loyalty-interchange/cli test http://127.0.0.1:3210 --api-key lip-dev-key

npm run lip -- init
npm run lip -- serve --api-key lip-dev-key
npm run lip -- doctor http://127.0.0.1:3210 --api-key lip-dev-key
npm run lip -- test http://127.0.0.1:3210 --api-key lip-dev-key

Useful commands for agent workflows:

Command	Purpose
lip init	Create lip.config.json with a default base URL and API-key env var
lip serve	Start the reference API, Admin dashboard, and SQLite sandbox
lip serve --program ./my-program.json	Boot with a custom program definition
lip doctor	Check discovery, health, auth, and capabilities
lip test	Run baseline non-destructive HTTP conformance checks
lip validate -s FoodserviceOrder ./order.json	Validate a payload against a schema
lip schemas	List schema names accepted by lip validate

Load a custom program when building a brand-specific integration — for example, a demo rewards program in a companion app:

LIP_WEBHOOK_URL=http://127.0.0.1:8787/loyalty/webhook \
LIP_WEBHOOK_SECRET=your-shared-secret \
npm run lip -- serve --program ./my-program.json --api-key lip-dev-key

See the Quickstart and Essentials for the full local setup path.

Spec and OpenAPI as agent context

LIP’s contract is machine-readable. Before implementing or modifying loyalty behavior, agents should load:

Resource	Path	Use when
OpenAPI 3.1 binding	spec/openapi.yaml	HTTP paths, auth, request/response shapes
JSON Schemas	spec/schemas/	Payload validation and code generation
Lifecycle rules	spec/lifecycle.md	Reserve → capture → reverse, refunds, idempotency
Foodservice profile	spec/profiles/foodservice.md	Order lines, modifiers, tenders, earning rules
Webhook profile	spec/webhooks.md	Signature verification and deduplication
Full lifecycle example	examples/typescript/full-lifecycle.ts	End-to-end SDK usage

When docs and spec disagree, treat spec/ as canonical.

Recommended agent read order for a new integration:

1. llms.txt

   Start with the index to orient on what exists.

2. Lifecycle rules

   Read spec/lifecycle.md for reserve → capture → reverse and idempotency.

3. Full lifecycle example

   Study examples/typescript/full-lifecycle.ts for end-to-end SDK usage.

4. TypeScript SDK

   Review the TypeScript SDK for operations and helpers.

5. API reference

   Cross-check paths against the API reference.

TypeScript SDK

The idiomatic client handles protocol context, validation, typed errors, and retry-safe reads. Agents should prefer LipClient over hand-rolled fetch calls:

import { LipClient } from "@loyalty-interchange/sdk";

const lip = new LipClient({
  baseUrl: process.env.LIP_URL!,
  apiKey: process.env.LIP_API_KEY!,
  source: { system: "my-ordering-app", instance: "production" }
});

const evaluation = await lip.orders.evaluate({
  member_id: memberId,
  order: draftOrder
});

Mutations must use stable idempotency keys derived from business identifiers (order id, reservation id) — never a random UUID per attempt. Retrying with a fresh key double-posts.

await lip.accruals.post(
  { member_id: memberId, order },
  { idempotencyKey: `accrual:${order.order_id}` }
);

Run the runnable example:

npm run example:sdk

See the TypeScript SDK for operations, money helpers, the order builder, and webhook verification.

Webhooks and event-driven agents

The reference platform emits signed CloudEvents after successful mutations (enrollment, accrual, adjustment, reserve, capture, reverse). Enable delivery with environment variables or the webhooks option on createDemoPlatform.

Receivers must verify the raw body with verifyWebhook from @loyalty-interchange/sdk and deduplicate on CloudEvent source + id. This is the primary event surface for agents that need to react to loyalty changes without polling the ledger.

1. Expose a receiver

   Your BFF or worker exposes POST /loyalty/webhook.

2. Receive signed events

   The LIP server pushes signed CloudEvents after mutations.

3. Verify, dedupe, and act

   The receiver verifies the raw body, deduplicates on source + id, and triggers downstream automation (CRM sync, push notifications, analytics).

A reference BFF that implements this pattern typically exposes received events at an endpoint like GET /loyalty/events for local inspection. See Webhooks for configuration and semantics.

Build integrations with AI coding tools

The BFF pattern

Mobile and web apps should not hold the LIP merchant API key. Agents building customer-facing apps should introduce a thin backend that:

• Owns customer auth (email, OTP, social — outside LIP today)
• Maps app users to member_id and enrolls via members/enroll
• Prices orders server-side and calls orders/evaluate for earn/redeem previews
• Runs checkout: redemptions/reserve → payment → accruals → redemptions/capture, with redemptions/reverse on failure
• Posts orders/adjust on refunds

A typical reference for this pattern is a mobile app → Node BFF → LIP server stack, with webhooks wired for event inspection. See Customer identity for where sign-in lives relative to the loyalty ledger.

Checkout preview

Never compute points or reward eligibility client-side when the program can change (tiers, campaigns, availability windows). Call orders/evaluate from your BFF and surface estimated_accrual and rewards[].status to the app.

Conformance before you ship

Agents should run these checks after implementing loyalty flows:

Published package

npx @loyalty-interchange/cli doctor http://127.0.0.1:3210 --api-key lip-dev-key
npx @loyalty-interchange/cli test http://127.0.0.1:3210 --api-key lip-dev-key
npm run test

npm run lip -- doctor http://127.0.0.1:3210 --api-key lip-dev-key
npm run lip -- test http://127.0.0.1:3210 --api-key lip-dev-key
npm run test

For a full-stack integration, add HTTP end-to-end tests that boot the real server and drive the lifecycle end to end.

AI prompts

Curated prompts help agents implement LIP correctly on the first pass — enroll flows, checkout lifecycle, webhook receivers, refund adjustments, and conformance checks.

AI prompts

Copy-ready prompts for every core loyalty flow.

What LIP does not provide

Agents often assume platform features that LIP does not provide. Do not implement these against LIP directly — build them in your BFF or a future platform module.

• Customer sign-in, OTP, or social auth (merchant-key API only)
• Campaigns, segments, push notifications, or CRM
• Program editing at runtime (boot-time --program, or Admin read-only today)
• Issued coupon wallets or QR check-in flows

See Punchh migration for migration mapping and the Migration guide for the full platform comparison.

Next steps

AI prompts

Ready-to-paste prompts for enroll, checkout, webhooks, refunds, and conformance.

TypeScript SDK

Operations, money helpers, the order builder, and webhook verification.