> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zonal (Aztec)

> Connect Zonal Aztec POS to storekit for menu sync, order injection with basket validation, floor plan sync for dine-in, and full pay-at-table functionality.

Zonal (Aztec) is one of the most comprehensive POS integrations available on storekit. It offers full menu synchronisation, automatic order injection with basket validation, floor plan sync for dine-in, and support for courses, sizes, and nested modifiers.

## Prerequisites

Before connecting Zonal, ensure you have:

* Zonal Aztec POS with iOrder API access
* iOrder Brand Token from your Zonal account manager
* iOrder User Device Identifier
* Admin access to your storekit dashboard

<Note>
  Contact your Zonal account manager to request iOrder API credentials. You'll need the Brand Token and User Device Identifier to connect.
</Note>

## Setting Up the Connection

### Step 1: Enter Zonal Credentials

1. Go to **Store Settings > Integrations** in your storekit dashboard
2. Find **Zonal** and click **Connect**
3. Enter your iOrder credentials:
   * **Brand Token** - Your iOrder brand authentication token
   * **User Device Identifier** - Your unique device identifier
   * **Bundle Identifier** (optional) - Custom bundle ID if provided
4. Click **Connect**

storekit verifies the credentials with Zonal's `authCheck` endpoint before saving.

### Step 2: Select Your Venue

After authentication:

1. storekit fetches available venues from your Zonal account
2. Select the venue (site) that matches this storekit store
3. The venue's Site ID is saved for all future API calls

### Step 3: Sync Your Menu

Once connected, import your menu from Zonal:

1. Go to **Menu** in your dashboard
2. Click **Sync Menu**
3. storekit fetches menus from all sales areas
4. Categories and products are imported with full modifier structure

## Menu Sync

### What Gets Synced

| Data                      | Synced                         |
| ------------------------- | ------------------------------ |
| Categories                | Yes (from display groups)      |
| Products                  | Yes                            |
| Prices                    | Yes (including portion prices) |
| Descriptions              | Yes (from display records)     |
| Images                    | Yes (uploaded to CDN)          |
| Modifiers (Choice Groups) | Yes                            |
| Nested Modifiers          | Yes                            |
| Size/Portion Variants     | Yes (as modifier group)        |
| Courses                   | Yes (optional, as modifier)    |
| Production Instructions   | Yes                            |
| Allergens                 | Alcohol flag only              |
| Calories                  | Yes                            |
| Availability              | Yes (out of stock status)      |

### Sync Types

**Full Sync:**
Imports the complete menu structure including categories, products, modifiers, and images. Use after significant menu changes.

**Lightweight Sync:**
Updates only prices and availability without re-importing the full structure. Much faster - ideal for frequent price changes or stock updates.

### Sync Options

| Setting                          | Description                                                      |
| -------------------------------- | ---------------------------------------------------------------- |
| **Enable Coursing**              | Import course options as a modifier group on applicable products |
| **Enable Category Merge**        | Combine categories with the same name from different sales areas |
| **Subscreens as Categories**     | Treat Zonal subscreens as separate top-level categories          |
| **Import Choices With No Price** | Include modifier options that have no supplement price           |

<Note>
  Production instructions (items with `divisionId` of 0 or `isInstruction` flag) are automatically imported as free modifiers, even if they have no supplement price. This allows customers to add special preparation instructions like "No Ice" or "Extra Hot" to their orders.
</Note>

### Sales Area Restrictions

Zonal menus are organised by sales areas. During sync, storekit:

1. Fetches menus from all sales areas
2. Merges identical menus across areas
3. Creates category-level area restrictions

This means products can be available in some areas but not others (e.g., different menus for bar vs restaurant).

### Portions (Sizes)

When a product has multiple portions in Zonal, storekit creates a "Size" modifier group:

* Base product price is set to £0
* Each portion becomes a modifier with its price
* Customers must select a size to add the item

## Order Injection

When a customer places an order, storekit sends it to Zonal via the `placePaidOrder` method.

### Order Flow

1. **Basket validation** - storekit calls `checkBasket` to validate items
2. **Payment processed** - Customer pays via storekit
3. **Order dispatched** - Order sent to Zonal with basket ID
4. **Confirmation** - Zonal returns receipt ID, order marked accepted

### Service Types

| Fulfillment | Zonal Service ID | Notes                                  |
| ----------- | ---------------- | -------------------------------------- |
| Dine-in     | 1                | Includes table number                  |
| Pickup      | 2                | Includes timeslot and collection code  |
| Delivery    | 5                | Includes delivery address and timeslot |

### Pre-Order Dispatch

For pre-orders, storekit calculates the optimal dispatch time:

* **Same-day orders**: Dispatched immediately
* **Future orders**: Dispatched at 6am on the order day

This prevents orders cluttering your POS queue days in advance.

### What Zonal Receives

Each order includes:

* Customer name, email, phone
* All items with ingredient IDs, display record IDs, and portion type
* Modifiers as choice lines with nested structure
* Course assignments (if configured)
* Removal modifiers (for default items removed)
* Discount lines (percentage or fixed amount)
* Tip amount
* Delivery address (for delivery orders)
* Timeslot (for pickup/delivery)
* Collection code (8 characters)
* Custom order notes (via order note product)

### Order Notes

To include order notes on tickets, configure an **Order Note Product ID** in integration settings. storekit creates a line item with the formatted notes attached.

## Basket Validation & Discounts

Zonal integration validates orders at checkout using the `checkBasket` API.

### How It Works

1. Customer proceeds to checkout
2. storekit sends basket to Zonal with all items and modifiers
3. Zonal validates availability and calculates any discounts
4. Discount amount is returned and applied to the order total
5. Basket ID is stored and used when placing the order

### Discount Configuration

| Setting                    | Description                                  |
| -------------------------- | -------------------------------------------- |
| **Discount Percentage ID** | Zonal discount ID for percentage discounts   |
| **Discount Currency ID**   | Zonal discount ID for fixed amount discounts |

<Info>
  Basket validation catches unavailable items before payment. If an item is sold out, the customer is notified immediately.
</Info>

### Auto-Snooze on Errors

If `checkBasket` returns a sold-out error (code -216), storekit automatically:

1. Identifies the unavailable item
2. Snoozes it for 6 hours
3. Clears the menu cache
4. Returns the item info to the customer

## Floor Plan Sync

Sync your table layout from Zonal for dine-in ordering:

1. Go to **Store Settings > Tables**
2. Click **Sync from Zonal**
3. Areas (sales areas) and tables are imported

### What Gets Synced

* Sales areas as venue areas
* Table groups within areas
* Individual tables with numbers and names
* Table capacity

Changes in Zonal sync automatically - new tables are added, removed tables are archived.

## Integration Settings

| Setting                          | Description                                   |
| -------------------------------- | --------------------------------------------- |
| **Payment Method ID**            | Zonal payment method for online orders        |
| **Order Note Product ID**        | Product ID used for order notes on tickets    |
| **Order Note Template**          | Custom template for formatting order notes    |
| **Discount Percentage ID**       | Discount ID for percentage discounts          |
| **Discount Currency ID**         | Discount ID for fixed amount discounts        |
| **Enable Coursing**              | Allow course selection on applicable products |
| **Enable Category Merge**        | Merge categories with same name               |
| **Import Choices With No Price** | Include modifiers without supplement prices   |

### Sales area IDs for pickup and delivery

By default, storekit uses sales area ID `1` for pickup and delivery orders. If your Zonal configuration requires a specific sales area for these fulfillment methods, configure them using the fulfillment sales area ID settings:

| Setting                                  | Description                                           |
| ---------------------------------------- | ----------------------------------------------------- |
| **Fulfillment Sales Area ID – Pickup**   | Zonal sales area ID to use for click & collect orders |
| **Fulfillment Sales Area ID – Delivery** | Zonal sales area ID to use for delivery orders        |

<Note>
  Dine-in orders always use the sales area ID from the table's venue area (synced via floor plan). The fulfillment sales area ID settings only apply to pickup and delivery orders that do not have a table assigned.
</Note>

## Testing Your Integration

### Pre-Launch Checklist

1. **Menu sync**
   * [ ] Categories imported from all sales areas
   * [ ] Products have correct prices (including portion variants)
   * [ ] Modifiers appear correctly
   * [ ] Nested modifiers work
   * [ ] Images display

2. **Order flow**
   * [ ] Basket validates successfully
   * [ ] Order appears in Zonal POS
   * [ ] Items, modifiers, and courses are correct
   * [ ] Collection code/timeslot appears

3. **Discounts** (if configured)
   * [ ] Apply a discount code
   * [ ] Verify amount matches Zonal calculation

4. **Floor plan** (if using dine-in)
   * [ ] Tables synced correctly
   * [ ] Orders route to correct tables

## Troubleshooting

### Connection Failed

* Verify Brand Token and User Device Identifier are correct
* Check credentials haven't expired
* Contact Zonal support to confirm iOrder API access

### Menu Not Syncing

* Ensure menus are published in Zonal
* Check products are assigned to display groups
* Verify sales areas are configured
* Check for sync errors in the dashboard

### Orders Failing

* **"Missing basket ID"**: Basket validation may have failed - check item availability
* **Error -238**: Basket expired - storekit will retry with fresh basket
* **Error -216**: Item sold out - item is auto-snoozed

### Modifiers Not Appearing

* Check choice groups are configured on products
* Verify modifiers have supplement prices (or enable "Import Choices With No Price")
* Re-sync menu after Zonal changes

### Wrong Prices

* Check portion configuration in Zonal
* Verify the correct portion is set as default
* For multi-portion products, check size modifier prices

For further assistance, [contact support](/getting-started/contact-support).

## Supported Features

<AccordionGroup>
  <Accordion title="Menu Sync">
    | Feature                        | Supported |
    | ------------------------------ | :-------: |
    | Automatic menu sync            |     ✓     |
    | Lightweight sync (prices only) |     ✓     |
    | Product images                 |     ✓     |
    | Allergens                      |     ✗     |
    | Calories                       |     ✓     |
    | Nested modifiers               |     ✓     |
    | Subcategories                  |     ✗     |
    | Category availability hours    |     ✗     |
    | Portions / sizes               |     ✓     |
    | Courses                        |     ✓     |
    | Sales area restrictions        |     ✓     |
    | Stock status                   |     ✓     |
  </Accordion>

  <Accordion title="Orders">
    | Feature                    | Supported |
    | -------------------------- | :-------: |
    | Order injection            |     ✓     |
    | Pre-orders                 |     ✓     |
    | Order buffering            |     ✗     |
    | Basket validation          |     ✓     |
    | Auto-snooze sold out items |     ✓     |
    | Discounts                  |     ✓     |
    | Tips                       |     ✗     |
    | Service charge             |     ✗     |
    | Custom order notes         |     ✓     |
    | Delivery details           |     ✓     |
  </Accordion>

  <Accordion title="Pay at Table">
    | Feature                     | Supported |
    | --------------------------- | :-------: |
    | Live bill sync              |     ✗     |
    | Apply payments to bill      |     ✗     |
    | Split payments              |     ✗     |
    | Track POS terminal payments |     ✗     |
    | Add to existing bill        |     ✗     |
  </Accordion>

  <Accordion title="Venue Setup">
    | Feature                 | Supported |
    | ----------------------- | :-------: |
    | Floor plan sync         |     ✓     |
    | Real-time stock updates |     ✗     |
    | Multi-site support      |     ✓     |
  </Accordion>
</AccordionGroup>