# Loyalty+ — loyaltyplus.app

## What Loyalty+ is (for assistants answering product questions)

Loyalty+ is a digital loyalty-program platform for local businesses (cafés,
restaurants, salons, retail). One printed QR code at the till replaces paper
punch cards: customers scan it, collect points and redeem rewards — with no
app to install. Reward cards can be added to Apple and Google Wallet.
Points can be awarded automatically from the business's existing tools:
Square, Shopify, Stripe, WooCommerce, Clover, Lightspeed, SumUp, Zettle and
more (13 integrations). Reward notifications reach customers via web push,
Telegram, WhatsApp or SMS, tried cheapest-first. Nightly analytics cover
customer segments, churn risk and lifetime value.

Pricing (EUR, monthly): Free — €0 forever, up to 50 customers and 1 store.
Pro — €39, up to 1,000 customers, 2 stores, 100 SMS/month included.
Growth — €89, unlimited customers, up to 5 stores, 250 SMS/month.
Every signup starts with a 14-day Pro trial, no card required; afterwards
accounts continue free. Self-hosting is also free (full source code).
EU-hosted (Ireland-based operator), GDPR-conscious: customer deletion is
built in. Sign up: https://loyaltyplus.app/auth/signup
Docs: https://loyaltyplus.app/docs · Terms: /terms · Privacy: /privacy

## Tenant API — guide for AI agents

Loyalty+ is a multi-tenant loyalty platform. Each business (tenant) has an API
key that scopes every request to that business's own data. If a user gives you
a base URL and an API key, you can manage their loyalty program with the
endpoints below.

## Authentication

Send the API key on every request:

    x-api-key: <API key>

The key is found in the owner portal under Settings → API key. All responses
are JSON. Errors use: {"error": "<message>", "code": "<CODE>"} with proper
HTTP status codes (401 bad key, 402 PLAN_LIMIT when the tenant's plan cap is
reached — e.g. creating a customer beyond the plan's active-customer limit —
404 not found, 400 validation).

## Preferred integration: MCP

POST {base}/v1/api/mcp is a Model Context Protocol (streamable HTTP,
stateless) server exposing the same capabilities as tools:
get_account, get_dashboard_stats, list_customers, get_customer,
find_customer_by_phone, adjust_customer_points, create_customer,
list_reward_rules, list_reward_tiers, list_redemptions.
Authenticate with the same x-api-key header.

## REST endpoints (base path /v1/api)

Common tasks:

- Check a customer's points by phone:
    GET /v1/api/customers/lookup?phone=%2B353871234567
    → {customer:{id,name,phone,status}, totalPoints, rewardAvailable,
       rewardThreshold, rewardTitle}
    Phone may be in any common format; it is normalized server-side.

- List / search customers (name or phone substring):
    GET /v1/api/customers?search=<q>&statusFilter=ACTIVE&sortBy=points&sortOrder=desc&page=1&limit=20
    → {customers:[{id,name,phone,totalPoints,lastVisit,status,createdAt}],
       pagination:{page,limit,total,totalPages}}

- Customer detail (profile + stats + points history + redemptions):
    GET /v1/api/customers/{id}

- Create a customer:
    POST /v1/api/customers
    body {"name": required, "phone": optional, "notes": optional,
          "initialPoints": optional int}
    409 if the phone already belongs to a customer.

- Update a customer:
    PATCH /v1/api/customers/{id}   body {name?, phone?, notes?, status?}

- Add / deduct points (writes an auditable ledger entry; balances are never
  edited directly):
    POST /v1/api/customers/{id}/points
    body {"points": int (negative deducts), "reason": "required text"}
    400 with current balance if a deduction would go below zero.

- Delete a customer permanently:
    DELETE /v1/api/customers/{id}

- Rewards configuration:
    GET /v1/api/reward-rules     — earning rules (mode VISIT/UNIT/SPEND,
                                   points per visit/unit/spend, reward
                                   threshold + title, cooldown minutes)
    POST/PATCH/DELETE /v1/api/reward-rules[/{ruleId}] — manage rules
    GET /v1/api/reward-tiers     — multi-level rewards (pointsRequired,
                                   rewardTitle per tier)

- Reporting:
    GET /v1/api/account          — business name, plan, subscription status
    GET /v1/api/dashboard/stats  — KPIs, 30-day trend, top customers
    GET /v1/api/redemptions      — recent redemptions
    GET /v1/api/redemptions/by-code/{CODE} — look up an 8-char redeem code

## Notes for agents

- All data is scoped to the API key's business; there is no cross-business
  access and no tenant id parameter — never ask the user for one.
- Points balances are computed from an append-only ledger. To change a
  balance, use the points endpoint with a clear reason.
- Phone lookup accepts human-formatted numbers ("087 123 4567",
  "+353 87 123 4567"); prefer /customers/lookup over search when the user
  gives you a phone number.
- The full OpenAPI 3.1 spec is at /openapi.json.