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

# Discounts

> How the POS Unified API exposes discounts at the line and order level, and the two patterns used by different POS systems.

## Discounts

POS systems apply discounts in two ways: directly on individual line items, or as a global reduction on the whole order. The Unified API normalises both into a consistent model that always keeps `total_discount` coherent with the line totals.

***

### Discount model

Every discount in the API is a `DiscountItem` object with three fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Display name of the discount (e.g. `"Staff meal"`, `"10% promo"`) |
| `total` | decimal | Yes | Tax-inclusive amount of the discount (3-decimal precision, positive value) |
| `type` | enum | Yes | Semantic type — see below |

#### `type` values

| Value | Meaning |
| - | - |
| `OFFERED` | The item or amount was offered to the customer (comp, staff meal, manager override). |
| `LOSS` | A markdown that reduces revenue intentionally (happy hour, clearance). |
| `UNKNOWN` | The source POS does not expose the discount type; Chift cannot determine it. |

> [!NOTE]
>
> `UNKNOWN` is the default when the POS does not provide this information. Do not treat it as an error.

***

### Line-level discounts

Each order line item (`OrderLineItem`) exposes a `discounts` list:

```json theme={null}
{
  "id": "line-001",
  "type": "product",
  "quantity": 1,
  "unit_price": 8.264,
  "total": 10.000,
  "tax_amount": 1.736,
  "tax_rate": 21,
  "discounts": [
    {
      "name": "Happy hour",
      "total": 2.000,
      "type": "LOSS"
    }
  ]
}
```

**The `discounts` list is informational.** The discount amounts are already subtracted from the line `total`. Do not subtract them again when you compute totals.

A line can carry multiple `DiscountItem` objects when several promotions apply simultaneously.

***

### Order-level discount

The order field `total_discount` holds the total tax-inclusive discount for the entire order:

```text theme={null}
order.total_discount = sum(line.discounts[*].total for all lines) + remaining_global_discount
```

`remaining_global_discount` is the part of the order-level reduction that the POS did not assign to any specific line. It is already subtracted from `order.total`.

When you need to split `remaining_global_discount` across VAT rates for accounting, see [Amounts, roundings and totals — Splitting a global discount](https://docs.chift.eu/unified-apis/pos/concepts/amounts-rounding.md#4-splitting-a-global-discount).

***

### The `general_discount` line type

Some POS systems do not use `DiscountItem` objects. Instead, they emit a dedicated line item of type `general_discount` to represent the discount:

```json theme={null}
{
  "id": "line-002",
  "type": "general_discount",
  "description": "Loyalty discount",
  "quantity": 1,
  "unit_price": -5.000,
  "total": -5.000,
  "tax_amount": -0.868,
  "tax_rate": 21
}
```

Key points for `general_discount` lines:

* `total` is **negative** — it reduces the order total.
* `discounts` is empty on this line type.
* `order.total_discount` reflects the absolute value: `5.000` in the example above.
* Treat this line like any other line when summing VAT per rate.

> [!NOTE]
>
> Some orders may combine both patterns: some lines carry `DiscountItem` objects while another line is of type `general_discount`. This depends on the source POS software.

***

### Summary

| Scenario | Where to look |
| - | - |
| Which discounts applied to a specific line | `OrderLineItem.discounts` |
| Total discount on the order | `OrderItem.total_discount` |
| POS uses a discount line instead of `DiscountItem` objects | `OrderLineItem` where `type = "general_discount"` |
| Semantic meaning of a discount | `DiscountItem.type` (`OFFERED`, `LOSS`, `UNKNOWN`) |
| How to split a global discount across VAT rates for accounting | [Amounts, roundings and totals](https://docs.chift.eu/unified-apis/pos/concepts/amounts-rounding.md#4-splitting-a-global-discount) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.