POS Integration Service

A standardized API layer that connects Cata to any Point-of-Sale (POS) system — one consistent interface for partners and operators, regardless of which POS is behind it.

New here? Three quick orientations:

If you're…	Start with
A POS vendor integrating your system into Cata	How Order Dispatch Works → Order Dispatch (Vendor Integration)
An operator deploying a Cata-supported POS (Revel today)	Built-In Transformer setup — credentials only, no code
A partner using Cata Loyalty alongside your own POS	Loyalty Points API Example

---

Overview — Use Cases for Connecting to Cata

Partners typically connect to Cata for one or both of these flows. Mix and match as your integration needs.

1. Menu & Order Integration

End-to-end POS integration: partner's menu surfaces in the Cata consumer app, orders placed in-app flow through to the partner's POS, and the partner reports fulfilment status back to Cata.

1. Push the menu into Cata. Partner POS syncs its product catalogue (items, modifiers, prices, availability) to Cata via the Standard API.
2. Cata displays the menu in the App. End-customers browse and order from the partner's merchant in Cata's consumer app.
3. Order paid → forwarded to the partner's system. Once the customer pays in the Cata app, the order is dispatched to the partner's POS so kitchen/operations can prepare it.
4. Partner returns order status. As the order progresses (accepted, preparing, ready, completed, rejected, cancelled), the partner reports status back via the Order Status endpoint. Cata mirrors the state to the customer.

Primary endpoints:

• POST /api/v1/outlets/sync — register / update merchant outlets
• POST /api/v1/products/sync — push the full product catalogue
• POST /api/v1/orders/dispatch — partner receives dispatched orders
• PATCH /api/v1/outlets/{id}/status · /busy — toggle OPEN / CLOSED / busy
• Order Status endpoint — partner reports fulfilment state back

See the Order Dispatch — Vendor Integration Walkthrough for a full step-by-step (mermaid diagrams, HMAC verification examples in 3 languages, smoke-test recipe). The Partner H2H tag in the API reference has the full endpoint list.

2. Loyalty Points

Partner drives customer loyalty from their own POS — earn points on purchase, redeem at checkout, read current balance. All three are thin proxies to Cata's loyalty service, authenticated by the same partner API key.

• Earn — credit points to a customer after a purchase (POST /api/v1/loyalty/earn-points).
• Burn / Redeem — deduct points the customer spends (POST /api/v1/loyalty/use-points).
• Balance — read current usable points plus the nearest upcoming expiry (GET /api/v1/loyalty/balance).

Both earn and burn are idempotent via a caller-supplied refCode — safe to replay on network retries.

See the Loyalty Points API Example for a full copy-paste walkthrough with real request/response bodies and error handling.

---

Architecture

flowchart LR
    Cata(["🏢 Cata"])

    subgraph PIS["POS Integration Service"]
        direction TB
        API["⚡ Standard API"]

        subgraph INT["Connectors"]
            direction LR
            D["Deliverect"]
            L["Lightspeed"]
            R["Revel"]
            A["Atlas"]
        end

        API <-->|transform| D & L & R & A
    end

    Cata <--> API

    D <--> DP[("Deliverect POS")]
    L <--> LP[("Lightspeed POS")]
    R <--> RP[("Revel POS")]
    A <--> AP[("Atlas Kitchen")]

---

Integration Styles

Each integrator absorbs the complexity of its POS — the Standard API never changes.

Integrator	Style	How it works
Deliverect	Webhook with payload	Pushes outlet & menu data directly
Lightspeed	Webhook + pull	Sends notification, integrator pulls data from Lightspeed API
Revel	API pull	Pulls menu & store data from Revel API (offline & online ordering)
Atlas	Webhook with payload	Sends store.created and other events with full payload

---

Menu APIs

	Menu V1	Menu V2
Approach	POS-driven menu sync	Cata-owned menu composition
How it works	POS pushes a full menu tree (Menu → Categories → Items → Modifiers)	Cata composes menus from flat products with sections, per-menu pricing, operating hours, and multi-store assignment
Data flow	POS → Cata (one-way push)	Cata UI → Cata Backend (full CRUD)
Pricing	Inherited from POS	Per-menu overrides (base_price, special_price)
Sections	Not supported (uses POS categories)	Custom sections (LIST, GRID, HIGHLIGHT, SWIMLANE)
Multi-store	One menu per store push	One menu assigned to many stores
Publish flow	Immediate on sync	Draft → Publish workflow
Status	Legacy — will be deprecated	Recommended for new integrations

Menu V2 Guide

---

Quick Links

• API Reference

  ---

  Full OpenAPI specification with all endpoints, schemas and examples.

  Open API Reference

• Swagger UI

  ---

  Interactive API explorer — try out endpoints directly from the browser.

  Open Swagger UI

• Getting Started

  ---

  Authentication, required headers, base URLs and async operations explained.

  Getting Started

• Webhooks

  ---

  Subscribe to real-time events — orders, menus, outlets and more.

  Webhook Guide