# Overview & Concepts

In this section, you will find a set of guides that walk you through developing and launching a Digital Ordering integration with LoyaltyPlant. It is intended to accompany the [Digital Ordering API specification](/digital-ordering/api/).

## 1. What Digital Ordering is

LoyaltyPlant offers a white-label e-commerce, loyalty and marketing platform for restaurant chains. Customers make orders through the mobile or web app, collect loyalty points for online and in-store orders, and spend those points on rewards in the app.

The Digital Ordering API allows customers to place orders online and have them processed in your POS system.

A working integration delivers three business outcomes:

- **Online sales through the loyalty app.** Customers who already use your loyalty program can discover the menu and order without leaving the app — counter pickup, delivery, or dine-in.
- **Loyalty earned and spent on every order.** Each Digital Ordering purchase earns points, and customers can attach rewards to the order — reward items arrive at your POS at zero price. LoyaltyPlant grants the points when the order completes and reverses them if it is later canceled or refunded.
- **One menu, always current.** LoyaltyPlant keeps a synchronized copy of your menu — items, prices, modifiers, stop-list — so the app shows what you actually sell at each sales outlet.

Deciding which rewards apply, calculating points, and crediting them all happen on the LoyaltyPlant side — your POS reports and fulfills the order, and applies what LoyaltyPlant sends.

## 2. Who calls whom

**Your service implements the API, and LoyaltyPlant calls it.** LoyaltyPlant is the HTTP client; the `/rest/*` endpoints described in this contract — getting the menu, checking availability, creating and reading orders — live on *your* server, and LoyaltyPlant sends requests to them. This inverts the usual "we host an API, you call us" model, and it is the single most common source of confusion for teams starting a Digital Ordering integration.

There is exactly one exception, and it runs the other way: the **order-status webhook**. When an order's status changes, *your* POS calls *LoyaltyPlant*.

```mermaid
flowchart LR
    Customer["Customer<br/>(LoyaltyPlant app)"] -->|"browses, orders, pays"| LP["LoyaltyPlant<br/>(Digital Ordering)"]
    LP -->|"GET /rest/menu, /rest/menu/revision,<br/>/rest/healthcheck; POST /rest/order, /rest/orders"| POS["YOUR POS endpoints<br/>(you host /rest/*)"]
    POS -.->|"POST /pos/v2/integrated<br/>(order-status webhook)"| LP
```

The diagram shows three directions of traffic:

| Direction | Who calls | What travels | Where it is documented |
|---|---|---|---|
| Customer → LoyaltyPlant | the customer | menu browsing, cart, checkout, payment — all inside the app | the LoyaltyPlant app (not part of this contract) |
| LoyaltyPlant → your POS (solid) | LoyaltyPlant | the five `/rest/*` calls — menu, revision, healthcheck, create order, read orders | [Ordering Flows](03-ordering-flows.md), the capability guides, the [spec](/digital-ordering/api/) |
| Your POS → LoyaltyPlant (dashed) | your POS | one status webhook per status change | the [Status Webhook Guide](06-status-webhook-guide.md), the `orderStatusWebhook` callback |

The endpoints you host all live under the base URL LoyaltyPlant stores for you (`{vendorBaseUrl}`, finalized at onboarding) with a `/rest` prefix; the webhook you send targets LoyaltyPlant's base URL (`{lpBaseUrl}`, also given at onboarding).

## 3. What you build

You build a service that hosts a number of `/rest/*` endpoints and sends one webhook back. The request/response schema for each operation lives in the [Digital Ordering API specification](/digital-ordering/api/).

This service enables three key capabilities, each walked end to end in the [Ordering Flows](03-ordering-flows.md) document:

- **Menu synchronization.** LoyaltyPlant pulls your menu on a schedule (never the reverse), using `getMenuRevision` to skip an unchanged menu and `getMenu` to re-import a changed one. An item you omit from the next menu is treated as a stop-list removal. Implementation steps are in the [Menu Sync Guide](04-menu-sync-guide.md).
- **Order injection.** After the customer pays, LoyaltyPlant healthchecks your sales outlet and, if every service is `UP`, calls `createOrder` to place the order; your POS returns the `posId` and `queueNumber`. Implementation steps are in the [Order Injection Guide](05-order-injection-guide.md).
- **Order status.** Your POS reports each status change to LoyaltyPlant via the webhook (push), and LoyaltyPlant can also poll `getOrders` (pull) as a safety net. The nine lifecycle statuses are defined on the spec's `OrderStatus` enum. Implementation steps are in the [Status Webhook Guide](06-status-webhook-guide.md).

## 4. Integration project stages

From the first meeting to production traffic, a Digital Ordering integration moves through five stages, each with a clear exit before the next begins.

```mermaid
flowchart LR
    K["1 · Kickoff"] --> D["2 · Development"]
    D --> T["3 · Testing & QA review"]
    T --> C["4 · Certification"]
    C --> P["5 · Pilot deployment"]
```

### 4.1 Kickoff

The LoyaltyPlant and vendor teams meet, walk through this documentation and the integration process, and agree on a communication channel — a direct chat with the LoyaltyPlant integrations team. LoyaltyPlant shares its development documentation, the integration checklist, a test app, test LP CRM access, and the certification test cases, and hands you your onboarding package — the test environment details and credentials you build and test against. You deploy and expose the `/rest/*` endpoints LoyaltyPlant will call (your `{vendorBaseUrl}`), and give LoyaltyPlant access to that test environment for the testing stage (see §4.3).

### 4.2 Development

You build the service that hosts the `/rest/*` endpoints and sends the [order status webhook](06-status-webhook-guide.md), working from this documentation set and the [Digital Ordering API specification](/digital-ordering/api/), with support from the LoyaltyPlant integrations team over the direct chat. Let LoyaltyPlant know about a week before you expect to finish so the testing slot can be scheduled.

### 4.3 Testing & QA review

You run the certification test cases against your integration and share a test report with LoyaltyPlant, along with access to your test environment. LoyaltyPlant reviews the integration flows against its test plan; any cases that work incorrectly come back to you as a fix list, you fix them, and the cycle repeats until everything passes. The [Integration Checklist](08-integration-checklist.md) is the checkbox-auditable gate this stage reviews against.

### 4.4 Certification

You give a short demo of the key flows, and LoyaltyPlant confirms the integration as certified.

### 4.5 Pilot deployment

The certified integration launches for the first client — a mutual client of LoyaltyPlant and your company. The first deployment runs with LoyaltyPlant representatives present, or is recorded and shared with LoyaltyPlant. Once the pilot is stable, the integration is rolled out to further mutual clients and locations.

---

**Next:** [General Requirements →](02-general-requirements.md)