# Templates

The ready-made Point of sale connector, its two tables, every column, and an example payload.

A template is a connector whose tables are ready made. There is nothing to map. Today there is one: **Point of sale**. An owner adds it from **Ingest** > **Add a connector** > **Receive** > **Point of sale**.

Adding it makes the connector (key `pos`), its two tables and a mapping that turns each menu item into an item in your model (see [Mappings](https://withmestra.com/docs/topos/mappings/)). Adding it again changes nothing. Saving makes a first key, shown once. Then your till sends data to the address under **Send to**, as described in [Send data to Mestra](https://withmestra.com/docs/topos/send-data/).

A template's tables are fixed. You can't add columns to them, and you can't delete them. Card numbers are masked to their last four digits as they arrive.

Nothing about a shopper or a staff member has a column. If a row you send carries such a field, it is left out of the table, and its name comes back as `dropped`.

## The routes

| Route   | Reads the list at | Writes          | Mode                                                           |
| ------- | ----------------- | --------------- | -------------------------------------------------------------- |
| `items` | `items`           | **Menu items**  | **Replace everything**: the menu is a full snapshot each time. |
| `sales` | `sales`           | **Sales lines** | **Append events**: each sold line is added once.               |

Each column is read from the field of the same name. You can send both lists in one payload or in separate ones. A payload without the `items` list leaves the menu untouched: the route reports `no_records` and nothing is marked gone.

## Menu items

A keyed table. One row for each item at each location. The key is `location` and `item_id`.

| Column      | Type       | Required |
| ----------- | ---------- | -------- |
| `location`  | Text       | Yes      |
| `item_id`   | Text       | Yes      |
| `name`      | Text       | Yes      |
| `price`     | Money      | Yes      |
| `currency`  | Text       | Yes      |
| `category`  | Text       | No       |
| `available` | True/false | No       |
| `stock`     | Number     | No       |

`currency` must be three upper-case letters, such as `NZD`. Anything else refuses the row with the reason `bad_currency`. `price` is whole cents.

```json
{
  "items": [
    {"location": "queen-st", "item_id": "1001", "name": "Flat white", "price": 450, "currency": "NZD", "category": "Coffee", "available": true, "stock": 40},
    {"location": "queen-st", "item_id": "1002", "name": "Cheese scone", "price": 595, "currency": "NZD", "available": true}
  ]
}
```

## Sales lines

A log table. One row for each line sold. The key is `location` and `line_id`, and the time column is `sold_at`.

| Column     | Type   | Required |
| ---------- | ------ | -------- |
| `location` | Text   | Yes      |
| `line_id`  | Text   | Yes      |
| `item_id`  | Text   | Yes      |
| `quantity` | Number | Yes      |
| `amount`   | Money  | Yes      |
| `currency` | Text   | Yes      |
| `sold_at`  | Time   | Yes      |

`currency` follows the same rule as for menu items. `sold_at` is an RFC 3339 time and is stored in UTC.

```json
{
  "sales": [
    {"location": "queen-st", "line_id": "T-88213-1", "item_id": "1001", "quantity": 2, "amount": 900, "currency": "NZD", "sold_at": "2026-11-14T09:12:40+13:00"},
    {"location": "queen-st", "line_id": "T-88213-2", "item_id": "1002", "quantity": 1, "amount": 595, "currency": "NZD", "sold_at": "2026-11-14T09:12:40+13:00"}
  ]
}
```

## Send both together

```bash
curl -sS -X POST "https://app.withmestra.com/ingest/pos" \
  -H "Authorization: Bearer $MESTRA_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

A good answer lists each route:

```json
{
  "landed": "5e2c8a40-91d7-4f63-b0a8-7d14c9e2f365",
  "routes": {
    "items": {"applied": 2, "unchanged": 0, "stale": 0, "gone": 0},
    "sales": {"applied": 2, "unchanged": 0, "stale": 0, "gone": 0}
  }
}
```
