> For the complete documentation index, see [llms.txt](https://docs.hivive.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivive.com.au/hardware/printer/docket-printing-behaviour.md).

# Docket printing behaviour

## Revised Docket Printing Settings

This document explains how the revised docket printing settings work.

### Scope

These settings apply to revised kitchen dockets, not to receipts, queue number prints, or normal manual docket reprints.

A docket is treated as revised when the order contains at least one item state:

* New item
* Cancelled item
* Modified item

Today, automatic revised docket printing is used for pay-at-counter dine-in order changes and cancellations. Backend-triggered automatic revised dockets are skipped for takeaway and online-order tables. Initial standard dockets are not controlled by these settings, even when printed during pay-at-counter checkout.

Each state can be configured separately with one of these print modes:

| Print mode                           | What it means                                                        |
| ------------------------------------ | -------------------------------------------------------------------- |
| Reprint whole docket                 | Print items in this state and include unchanged items on the docket. |
| Only print new/edited/cancelled item | Print only changed items that are allowed by their state setting.    |
| Don't print                          | Do not print items in this state.                                    |

### Decision Rules

The current design uses these rules for revised dockets:

1. If any changed item state is set to `Reprint whole docket` and that state exists in the revised docket, unchanged items are included.
2. Items set to `Don't print` are excluded, even when another state triggers `Reprint whole docket`.
3. Items set to `Only print new/edited/cancelled item` are included, but they do not cause unchanged items to print.
4. If no printable changed items remain after filtering, no revised docket prints for that printer location.
5. Standard dockets are not affected by these settings.
6. For quantity-only increases, printer clients treat the positive quantity delta as `New item` before applying these rules.

### Quantity Changes

When an existing cart item is edited only by changing its quantity, the backend keeps the item state as `Modified item` and also sends a `quantityDelta`.

Printer clients use a positive `quantityDelta` as an effective `New item` for revised docket printing:

| Quantity change                      | Backend state   | Print state used by printer settings | Quantity printed |
| ------------------------------------ | --------------- | ------------------------------------ | ---------------- |
| `2x Beef Burger` to `3x Beef Burger` | `Modified item` | `New item`                           | `1x Beef Burger` |
| `2x Beef Burger` to `4x Beef Burger` | `Modified item` | `New item`                           | `2x Beef Burger` |

This means a quantity increase is controlled by the `New item` print setting, not the `Modified item` print setting. For example, if `New item` is set to `Only print new/edited/cancelled item` and `Modified item` is set to `Don't print`, increasing `2x Beef Burger` to `3x Beef Burger` prints a revised docket line for `1x Beef Burger`.

If `New item` is set to `Don't print`, that same quantity increase does not print, even if `Modified item` is set to `Reprint whole docket`, because the printer-side state used for the positive delta is `New item`.

If `New item` is set to `Reprint whole docket`, a quantity increase can also include unchanged items at that printer location. For example, increasing `2x Beef Burger` to `3x Beef Burger` can print `1x Beef Burger` as new plus unchanged items on the same location docket.

The order data still represents the line as modified with the final order quantity. The positive delta only changes how the revised docket is filtered and displayed.

Current limits:

| Case                                                            | Current behavior                                                                                                                                                                    |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Quantity decrease, such as `3x Beef Burger` to `1x Beef Burger` | Still uses `Modified item`; it prints the current line, `1x Beef Burger`, only when the `Modified item` setting allows it. It is not split into a `2x Beef Burger` cancelled delta. |
| Quantity change plus a note, option, price, or takeaway change  | Still uses `Modified item`; the positive-delta `New item` behavior applies only to quantity-only changes.                                                                           |

### Printer Locations

The revised docket settings are applied before the docket is split by printer location. After that, each printer location still receives only the items assigned to that location.

If `Reprint whole docket` includes unchanged items, those unchanged items print only on a printer location that also has at least one printable changed line. A printer location with unchanged items only does not print a revised docket.

For example, if a Kitchen item is modified and Bar items are unchanged, `Reprint whole docket` prints the Kitchen changed item plus Kitchen unchanged items. The Bar printer does not print a revised docket unless the Bar location also has a printable changed item or option line.

### Option Changes And Locations

Current backend order updates represent option changes at the parent cart item level.

| Option update                             | Revised docket state produced today | Printed behaviour                                                                                                        |
| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Option added                              | Parent item is `Modified item`      | Prints the modified parent item with the current option list.                                                            |
| Option changed from one option to another | Parent item is `Modified item`      | Prints the modified parent item with the new/current option list. The old option is not printed separately as cancelled. |
| Option removed                            | Parent item is `Modified item`      | Prints the modified parent item without the removed option. The removed option is not printed separately as cancelled.   |

For location-specific options, Android POS routes the option line to the option's configured printer location. If a changed/current option has a different location from the parent food item, that option line prints at the option location and the parent food item prints at the food item's location.

If the parent item is marked as changed, location-specific options inherit that parent item state for printing. This lets the option's configured printer location receive a revised line even when the backend only marked the parent cart item as changed.

Because removed options are not sent as separate cancelled option lines today, removing an option that used to belong to a different location does not print a separate cancelled line at that old option location. It is represented only by the parent item being `Modified item`.

The `Modified item` print setting controls these option-change dockets. For example, if `Modified item` is set to `Don't print`, option-only add/change/remove updates do not print a revised docket unless another printable changed state is present.

### Known Edge Cases

These edge cases are not handled yet. They describe expected current behavior, not desired final behavior.

| Edge case                                                    | Current behavior                                                                                                                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reordering the same option IDs                               | Can still look like an option change in some backend matching paths, so the parent item may print as `Modified item`.                                                     |
| Quantity decrease                                            | Still treated as `Modified item`; it is not split into a cancelled delta line.                                                                                            |
| Quantity change plus option, note, takeaway, or price change | Still represented as one `Modified item`, so the `New item` positive-delta behavior does not apply.                                                                       |
| Changing an item from one option variant to another          | Prints the new/current variant as modified; the old variant is not printed separately as cancelled.                                                                       |
| Removing an option                                           | Prints the modified parent item without the removed option; the removed option is not printed separately as cancelled.                                                    |
| Removing a location-specific option                          | Does not print a separate cancelled option line at the option's previous printer location. It is represented only by the parent item being `Modified item`.               |
| Editing multiple variants of the same food in one update     | Backend matching can still pair an unmatched old and new item by food ID only, so the resulting new/modified/cancelled pairing may not perfectly match the user's intent. |

### Combination Grid

This grid assumes the revised docket contains the changed states shown in the settings. If a state does not exist in the revised docket, its setting has no effect. Quantity-only increases are counted as `New item` in this grid because the printer clients apply the positive `quantityDelta` override before filtering.

| New item setting                     | Cancelled item setting               | Modified item setting                | Printed result                                |
| ------------------------------------ | ------------------------------------ | ------------------------------------ | --------------------------------------------- |
| Don't print                          | Don't print                          | Don't print                          | Nothing prints                                |
| Don't print                          | Don't print                          | Only print new/edited/cancelled item | Modified items only                           |
| Don't print                          | Don't print                          | Reprint whole docket                 | Modified items and unchanged items            |
| Don't print                          | Only print new/edited/cancelled item | Don't print                          | Cancelled items only                          |
| Don't print                          | Only print new/edited/cancelled item | Only print new/edited/cancelled item | Cancelled and modified items only             |
| Don't print                          | Only print new/edited/cancelled item | Reprint whole docket                 | Cancelled, modified, and unchanged items      |
| Don't print                          | Reprint whole docket                 | Don't print                          | Cancelled items and unchanged items           |
| Don't print                          | Reprint whole docket                 | Only print new/edited/cancelled item | Cancelled, modified, and unchanged items      |
| Don't print                          | Reprint whole docket                 | Reprint whole docket                 | Cancelled, modified, and unchanged items      |
| Only print new/edited/cancelled item | Don't print                          | Don't print                          | New items only                                |
| Only print new/edited/cancelled item | Don't print                          | Only print new/edited/cancelled item | New and modified items only                   |
| Only print new/edited/cancelled item | Don't print                          | Reprint whole docket                 | New, modified, and unchanged items            |
| Only print new/edited/cancelled item | Only print new/edited/cancelled item | Don't print                          | New and cancelled items only                  |
| Only print new/edited/cancelled item | Only print new/edited/cancelled item | Only print new/edited/cancelled item | New, cancelled, and modified items only       |
| Only print new/edited/cancelled item | Only print new/edited/cancelled item | Reprint whole docket                 | New, cancelled, modified, and unchanged items |
| Only print new/edited/cancelled item | Reprint whole docket                 | Don't print                          | New, cancelled, and unchanged items           |
| Only print new/edited/cancelled item | Reprint whole docket                 | Only print new/edited/cancelled item | New, cancelled, modified, and unchanged items |
| Only print new/edited/cancelled item | Reprint whole docket                 | Reprint whole docket                 | New, cancelled, modified, and unchanged items |
| Reprint whole docket                 | Don't print                          | Don't print                          | New items and unchanged items                 |
| Reprint whole docket                 | Don't print                          | Only print new/edited/cancelled item | New, modified, and unchanged items            |
| Reprint whole docket                 | Don't print                          | Reprint whole docket                 | New, modified, and unchanged items            |
| Reprint whole docket                 | Only print new/edited/cancelled item | Don't print                          | New, cancelled, and unchanged items           |
| Reprint whole docket                 | Only print new/edited/cancelled item | Only print new/edited/cancelled item | New, cancelled, modified, and unchanged items |
| Reprint whole docket                 | Only print new/edited/cancelled item | Reprint whole docket                 | New, cancelled, modified, and unchanged items |
| Reprint whole docket                 | Reprint whole docket                 | Don't print                          | New, cancelled, and unchanged items           |
| Reprint whole docket                 | Reprint whole docket                 | Only print new/edited/cancelled item | New, cancelled, modified, and unchanged items |
| Reprint whole docket                 | Reprint whole docket                 | Reprint whole docket                 | Everything prints                             |

### Examples

Use this original kitchen docket for the examples below:

* Table 12
* 1x Beef Burger
* 1x Fries
* 1x Lemonade

#### Example 1: A modified item reprints the whole docket

The staff edit the order and add a note to `1x Beef Burger`.

Settings:

* New item: `Don't print`
* Cancelled item: `Don't print`
* Modified item: `Reprint whole docket`

Printed revised docket:

* 1x Beef Burger (modified)
* 1x Fries (unchanged)
* 1x Lemonade (unchanged)

The modified item prints because modified items are set to `Reprint whole docket`. Fries and Lemonade also print because that setting includes unchanged items.

#### Example 2: A different edit prints only the changed items

The staff edit the same order and add `1x Onion Rings`.

Settings:

* New item: `Only print new/edited/cancelled item`
* Cancelled item: `Don't print`
* Modified item: `Only print new/edited/cancelled item`

Printed revised docket:

* 1x Onion Rings (new)

The new item prints because new items are set to `Only print new/edited/cancelled item`. Beef Burger, Fries, and Lemonade do not print because they were unchanged.

#### Example 3: A cancelled item is excluded even when another edit reprints the docket

The staff edit the same order in two ways:

* Add `1x Onion Rings`
* Cancel `1x Lemonade`

Settings:

* New item: `Reprint whole docket`
* Cancelled item: `Don't print`
* Modified item: `Don't print`

Printed revised docket:

* 1x Onion Rings (new)
* 1x Beef Burger (unchanged)
* 1x Fries (unchanged)

The new item triggers `Reprint whole docket`, so unchanged items are included. Lemonade is still excluded because cancelled items are set to `Don't print`.

#### Example 4: A quantity increase prints as a new item

The original order has `2x Beef Burger`. Staff increase it to `3x Beef Burger` without changing options, notes, price, or takeaway status.

Settings:

* New item: `Only print new/edited/cancelled item`
* Cancelled item: `Don't print`
* Modified item: `Don't print`

Printed revised docket:

* 1x Beef Burger (new)

The backend still sends the cart item as `Modified item` with final quantity `3`, plus `quantityDelta: 1`. The printer uses the positive delta as `New item`, so the docket prints only the added quantity.