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

# LineItem

> Look up each field of an invoice line, with its type, its rules and an example value.

## Overview

The `LineItem` schema defines one line of an invoice or credit note. Each line is a product, a service or a different billable item. You send line items in the `items` array of the [Document schema](/api-reference/schemas/document).

<Note>
  All fields are optional in the schema. For a complete line, send `description`, `quantity`, `unit`, `unit_price`, `amount` and `tax_rate`.
</Note>

## Basic fields

<ParamField body="description" type="string">
  Description of the product or service. The API writes it as the item name and the item description in the UBL.

  Example: `"Consulting hours - September 2026"`
</ParamField>

<ParamField body="product_code" type="string">
  Product code or SKU of the seller. The API writes it to `cac:Item/cac:SellersItemIdentification/cbc:ID`.

  Example: `"PROD-001"`
</ParamField>

<ParamField body="date" type="null">
  Reserved field. In the current OpenAPI specification this field accepts only `null`, and the API does not write it to the generated UBL. Do not send a value. For the period of a delivery or service, use `service_start_date` and `service_end_date` on the document.

  Example: `null`
</ParamField>

## Quantity and unit

<ParamField body="quantity" type="number">
  Quantity of items, with a maximum of 4 decimals. It can be negative for credit notes or corrections.

  Example: `10`, `2.5`
</ParamField>

<ParamField body="unit" type="enum">
  [Unit code](/glossary#unit-code) of the unit of measure (UN/ECE Recommendation 20).

  Common values:

  * `C62` - Units or pieces (most common)
  * `HUR` - Hours
  * `DAY` - Days
  * `MTR` - Metres
  * `KGM` - Kilograms
  * `LTR` - Litres
  * `MTK` - Square metres
  * `MTQ` - Cubic metres
  * `KWH` - Kilowatt hours

  Example: `"HUR"`
</ParamField>

## Pricing

<ParamField body="unit_price" type="number">
  Net price of one unit without VAT, with a maximum of 4 decimals. This is the item net price (BT-146), after an item price discount and before line allowances and charges.

  Example: `100.00`, `0.0125`
</ParamField>

<Note>
  `price_base_quantity` is not an input field. The price is always the price of one unit: the API writes `cac:Price/cbc:BaseQuantity` with the value `1` and ignores a `price_base_quantity` that you send. If your price is for 100 or 1000 units, divide it and send the price of one unit in `unit_price` (4 decimals are available).
</Note>

<ParamField body="amount" type="number">
  Net amount of the line without VAT (BT-131), with a maximum of 2 decimals. Line allowances are subtracted and line charges are added.

  Calculation: `(quantity × unit_price) - allowances + charges`

  Send this value. The API writes it as the UBL line extension amount and uses it for the document totals. It can be negative for credit notes or corrections.

  Example: `1000.00`
</ParamField>

## Tax

<ParamField body="tax_rate" type="number" default="0.00">
  VAT rate as a percentage from 0 to 100, with 2 decimals. Send a number. A string such as `"21.00"` is also accepted for backward compatibility.

  Common Belgian rates:

  * `21.00` - Standard rate
  * `6.00` - Reduced rate
  * `0.00` - Zero-rated

  Example: `21.00`
</ParamField>

<ParamField body="tax" type="number">
  VAT amount of the line, with a maximum of 2 decimals.

  Calculation: `amount × (tax_rate / 100)`

  When it is absent, the API calculates it from `amount` and `tax_rate`.

  Example: `210.00` (21% of 1000.00)
</ParamField>

## Item attributes

<ParamField body="item_attributes" type="array">
  Properties of the item, such as colour or size (BG-32). The API writes each attribute to `cac:Item/cac:AdditionalItemProperty`.

  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Name of the attribute (BT-160).

      Example: `"Colour"`
    </ParamField>

    <ParamField body="value" type="string">
      Value of the attribute (BT-161). The API does not write an attribute without a value to the UBL.

      Example: `"Blue"`
    </ParamField>
  </Expandable>

  Example:

  ```json theme={null}
  [
    { "name": "Colour", "value": "Blue" },
    { "name": "Size", "value": "XL" }
  ]
  ```
</ParamField>

## Allowances and charges

<ParamField body="allowances" type="array">
  Line-level allowances (discounts) for this item only, for example a bulk discount or a promotion.

  <Expandable title="properties">
    <ParamField body="amount" type="number">
      Allowance amount without VAT, with a maximum of 2 decimals. The API does not calculate this value from `multiplier_factor` and `base_amount`. You must send it.

      Example: `500.00`
    </ParamField>

    <ParamField body="reason" type="string">
      Reason for the allowance as text.

      Example: `"Bulk discount"`
    </ParamField>

    <ParamField body="reason_code" type="enum">
      Allowance reason code (UNCL5189). Permitted values: `41`, `42`, `60`, `62`, `63`, `64`, `65`, `66`, `67`, `68`, `70`, `71`, `88`, `95`, `100`, `102`, `103`, `104`, `105`. Send the code as a string.

      Example: `"95"` (discount)
    </ParamField>

    <ParamField body="multiplier_factor" type="number">
      Percentage of the allowance, from 0 to 100, with a maximum of 2 decimals. To state 10%, send `10`. Send it together with `base_amount`.

      Example: `10`
    </ParamField>

    <ParamField body="base_amount" type="number">
      Amount to which the percentage applies, with a maximum of 2 decimals. Send it together with `multiplier_factor`.

      Example: `5000.00`
    </ParamField>

    <ParamField body="tax_code" type="enum" default="S">
      VAT category code. The API does not write a tax category on a line-level allowance in the UBL. The line uses the tax category of the line item.
    </ParamField>

    <ParamField body="tax_rate" type="number" default="21.00">
      VAT rate as a percentage. The API does not write it on a line-level allowance in the UBL.
    </ParamField>
  </Expandable>

  Example of a 10% allowance:

  ```json theme={null}
  [
    {
      "reason": "Bulk discount",
      "reason_code": "95",
      "multiplier_factor": 10,
      "base_amount": 5000.00,
      "amount": 500.00
    }
  ]
  ```
</ParamField>

<ParamField body="charges" type="array">
  Line-level charges (fees) for this item only, for example special handling or customisation.

  <Expandable title="properties">
    <ParamField body="amount" type="number">
      Charge amount without VAT, with a maximum of 2 decimals. The API does not calculate this value from `multiplier_factor` and `base_amount`. You must send it.

      Example: `50.00`
    </ParamField>

    <ParamField body="reason" type="string">
      Reason for the charge as text.

      Example: `"Additional packaging"`
    </ParamField>

    <ParamField body="reason_code" type="enum">
      Charge reason code (UNCL7161). The full list of permitted values is in the `ChargeReasonCode` schema of the [API reference](/api-reference).

      Example: `"ABL"` (additional packaging)
    </ParamField>

    <ParamField body="multiplier_factor" type="number">
      Percentage of the charge, from 0 to 100, with a maximum of 2 decimals. To state 10%, send `10`. Send it together with `base_amount`.

      Example: `10`
    </ParamField>

    <ParamField body="base_amount" type="number">
      Amount to which the percentage applies, with a maximum of 2 decimals. Send it together with `multiplier_factor`.

      Example: `500.00`
    </ParamField>

    <ParamField body="tax_code" type="enum" default="S">
      VAT category code. The API does not write a tax category on a line-level charge in the UBL.
    </ParamField>

    <ParamField body="tax_rate" type="number" default="21.00">
      VAT rate as a percentage. The API does not write it on a line-level charge in the UBL.
    </ParamField>
  </Expandable>

  Example:

  ```json theme={null}
  [
    {
      "reason": "Additional packaging",
      "reason_code": "ABL",
      "amount": 50.00
    }
  ]
  ```
</ParamField>

See [Advanced invoicing](/guides/advanced-invoicing) for document-level allowances and charges and their effect on the totals.

## Examples

### Simple line item

```json theme={null}
{
  "description": "Product A",
  "quantity": 10,
  "unit": "C62",
  "unit_price": 100.00,
  "amount": 1000.00,
  "tax_rate": 21.00
}
```

* Amount: 10 × 100.00 = 1000.00
* Tax: 1000.00 × 21% = 210.00
* Total with tax: 1210.00

### Service line item

```json theme={null}
{
  "description": "Consulting services - September 2026",
  "quantity": 40,
  "unit": "HUR",
  "unit_price": 150.00,
  "amount": 6000.00,
  "tax_rate": 21.00
}
```

* Amount: 40 hours × 150.00 = 6000.00
* Tax: 6000.00 × 21% = 1260.00
* Total with tax: 7260.00

### Line item with item attributes

```json theme={null}
{
  "description": "T-shirt with logo",
  "product_code": "TS-BLUE-XL",
  "quantity": 25,
  "unit": "C62",
  "unit_price": 12.00,
  "amount": 300.00,
  "tax_rate": 21.00,
  "item_attributes": [
    { "name": "Colour", "value": "Blue" },
    { "name": "Size", "value": "XL" }
  ]
}
```

The receiver gets the attributes in the UBL:

```xml theme={null}
<cac:AdditionalItemProperty>
  <cbc:Name>Colour</cbc:Name>
  <cbc:Value>Blue</cbc:Value>
</cac:AdditionalItemProperty>
<cac:AdditionalItemProperty>
  <cbc:Name>Size</cbc:Name>
  <cbc:Value>XL</cbc:Value>
</cac:AdditionalItemProperty>
```

### Line item with a percentage allowance

```json theme={null}
{
  "description": "Premium product B",
  "quantity": 100,
  "unit": "C62",
  "unit_price": 50.00,
  "amount": 4500.00,
  "tax_rate": 21.00,
  "allowances": [
    {
      "reason": "Bulk discount",
      "reason_code": "95",
      "multiplier_factor": 10,
      "base_amount": 5000.00,
      "amount": 500.00
    }
  ]
}
```

* Base: 100 × 50.00 = 5000.00
* Allowance: 5000.00 × 10% = 500.00
* Amount: 4500.00
* Tax: 4500.00 × 21% = 945.00
* Total with tax: 5445.00

### Line item with a charge

```json theme={null}
{
  "description": "Fragile equipment",
  "quantity": 1,
  "unit": "C62",
  "unit_price": 500.00,
  "amount": 550.00,
  "tax_rate": 21.00,
  "charges": [
    {
      "reason": "Additional packaging",
      "reason_code": "ABL",
      "amount": 50.00
    }
  ]
}
```

* Base: 1 × 500.00 = 500.00
* Charge: 50.00
* Amount: 550.00
* Tax: 550.00 × 21% = 115.50
* Total with tax: 665.50

### Lines with different tax rates

```json theme={null}
{
  "items": [
    {
      "description": "Standard product",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": 21.00
    },
    {
      "description": "Reduced rate product (books)",
      "quantity": 5,
      "unit": "C62",
      "unit_price": 20.00,
      "amount": 100.00,
      "tax_rate": 6.00
    },
    {
      "description": "Zero-rated product",
      "quantity": 3,
      "unit": "C62",
      "unit_price": 200.00,
      "amount": 600.00,
      "tax_rate": 0.00
    }
  ]
}
```

* Line 1: 1000.00 + 210.00 tax (21%) = 1210.00
* Line 2: 100.00 + 6.00 tax (6%) = 106.00
* Line 3: 600.00 + 0.00 tax (0%) = 600.00
* Total with tax: 1916.00

## Calculation flow

1. Base amount: `quantity × unit_price`
2. Subtract the line-level allowances.
3. Add the line-level charges.
4. Line amount: `base - allowances + charges`, rounded half-up to 2 decimals. This is the value of `amount`.
5. Tax: `amount × (tax_rate / 100)`

Example with an allowance and a charge:

```json theme={null}
{
  "description": "Configured product",
  "quantity": 20,
  "unit": "C62",
  "unit_price": 100.00,
  "amount": 1850.00,
  "tax_rate": 21.00,
  "allowances": [
    {
      "amount": 200.00,
      "reason": "Volume discount"
    }
  ],
  "charges": [
    {
      "amount": 50.00,
      "reason": "Customisation fee"
    }
  ]
}
```

1. Base: 20 × 100.00 = 2000.00
2. Allowance: 200.00
3. Charge: 50.00
4. Amount: 1850.00
5. Tax (21%): 388.50

<Note>
  In the document totals, the API calculates VAT for each tax group ([tax category](/glossary#tax-category-code) and rate), not for each line. See [Normalisation and rounding](/api-reference/schemas/document#normalisation-and-rounding).
</Note>

## Best practices

<AccordionGroup>
  <Accordion title="Write a specific description">
    A specific description tells the customer what the line is for.

    Recommended:

    ```json theme={null}
    {
      "description": "Consulting services - Project XYZ - September 2026"
    }
    ```

    Not recommended:

    ```json theme={null}
    {
      "description": "Services"
    }
    ```
  </Accordion>

  <Accordion title="Use the applicable unit">
    Use the unit that agrees with the item:

    * Products and goods: `"C62"` (pieces)
    * Services by time: `"HUR"` (hours) or `"DAY"` (days)
    * Materials by weight: `"KGM"` (kilograms)
    * Materials by volume: `"LTR"` (litres)
  </Accordion>

  <Accordion title="Send the tax rate as a number">
    `tax_rate` is a number from 0 to 100. A string is accepted for backward compatibility, but a number with 2 decimals is preferred.

    Preferred:

    ```json theme={null}
    {
      "tax_rate": 21.00
    }
    ```

    Also accepted:

    ```json theme={null}
    {
      "tax_rate": "21.00"
    }
    ```
  </Accordion>

  <Accordion title="Stay within the decimal limits">
    * Unit prices: a maximum of 4 decimals
    * Quantities: a maximum of 4 decimals
    * Amounts and tax rates: 2 decimals
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Document" icon="file-lines" href="/api-reference/schemas/document">
    Look up the document fields and their conversion to UBL.
  </Card>

  <Card title="Advanced invoicing" icon="percent" href="/guides/advanced-invoicing">
    Apply allowances and charges on the line and on the document.
  </Card>

  <Card title="Invoice totals and calculations" icon="calculator" href="/guides/invoice-totals">
    Calculate the totals from the line amounts.
  </Card>

  <Card title="Create e-invoices" icon="file-invoice" href="/guides/creating-invoices">
    Create and send an invoice with line items.
  </Card>
</CardGroup>


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