> ## 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

> Invoice line item structure

## Overview

The `LineItem` schema defines individual line items within an invoice or credit note. Each line item represents a product, service, or other billable item.

<Note>
  All fields are optional, but providing `description`, `quantity`, `unit_price`, and `tax_rate` creates complete, clear line items.
</Note>

## Basic Fields

<ParamField body="description" type="string">
  Description of the product or service

  This is the primary field for identifying what is being sold.

  Example: `"Professional Services"`, `"Product A - Premium Edition"`, `"Consulting hours - October 2024"`
</ParamField>

<ParamField body="product_code" type="string">
  Product code or SKU

  Internal reference code for the product/service.

  Example: `"PROD-001"`, `"SKU-PREMIUM-A"`
</ParamField>

## Quantity and Unit

<ParamField body="quantity" type="number">
  Quantity of items (max 4 decimal places)

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

<ParamField body="unit" type="enum">
  Unit of measure code (UN/ECE Recommendation 20)

  Common values:

  * `C62` - Units/pieces (most common)
  * `HUR` - Hours
  * `DAY` - Days
  * `MTR` - Meters
  * `KGM` - Kilograms
  * `LTR` - Liters
  * `MTK` - Square meters
  * `MTQ` - Cubic meters
  * `KWH` - Kilowatt hours

  Example: `"C62"`, `"HUR"`, `"DAY"`
</ParamField>

## Pricing

<ParamField body="unit_price" type="number">
  Price per unit (max 4 decimal places), **excluding VAT**

  This is the price for a single unit before any allowances or charges.

  Example: `100.00`, `50.99`, `1250.00`
</ParamField>

<ParamField body="amount" type="number">
  Total line amount (max 2 decimal places), **excluding VAT**

  Total amount for this line item after subtracting allowances and adding charges. This is the invoice line net amount (BT-131), exclusive of VAT.

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

  Provide this value: it is used directly as the UBL line extension amount and drives the document totals. Compute it yourself from quantity, unit\_price, allowances, and charges. Can be negative for credit notes or corrections.

  Example: `1000.00`, `950.00` (after €50 discount)
</ParamField>

## Tax

<ParamField body="tax_rate" type="number" default="0.00">
  VAT/tax rate as a percentage (0–100), with 2 decimal places. Sent as 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`, `6.00`, `0.00`
</ParamField>

<ParamField body="tax" type="number">
  Total VAT/tax amount for this line item (max 2 decimal places)

  **Calculation**: `amount × (tax_rate / 100)`

  If not provided, automatically calculated from `amount` and `tax_rate`.

  Example: `210.00` (21% of €1000), `126.00` (21% of €600)
</ParamField>

## Allowances (Discounts)

<ParamField body="allowances" type="array">
  Line-level allowances (discounts) applied to this specific item

  Use for product-specific discounts (bulk discounts, promotions, etc.)

  Example:

  ```json theme={null}
  [
    {
      "amount": 100.00,
      "reason": "Bulk discount (10%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
  ```

  See [Advanced Invoicing guide](/guides/advanced-invoicing) for details.
</ParamField>

## Charges (Fees)

<ParamField body="charges" type="array">
  Line-level charges (fees) applied to this specific item

  Use for product-specific fees (special handling, customization fees, etc.)

  Example:

  ```json theme={null}
  [
    {
      "amount": 50.00,
      "reason": "Special handling - fragile item",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
  ```

  See [Advanced Invoicing guide](/guides/advanced-invoicing) for details.
</ParamField>

## Examples

### Simple Line Item

Basic product line:

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

**Calculation**:

* Amount: 10 × €100 = €1,000.00
* Tax: €1,000 × 21% = €210.00
* **Total**: €1,210.00

### Service Line Item

Hourly services:

```json theme={null}
{
  "description": "Consulting Services - October 2024",
  "quantity": 40,
  "unit": "HUR",
  "unit_price": 150.00,
  "tax_rate": "21.00"
}
```

**Calculation**:

* Amount: 40 hours × €150 = €6,000.00
* Tax: €6,000 × 21% = €1,260.00
* **Total**: €7,260.00

### Line Item with Discount

Product with bulk discount:

```json theme={null}
{
  "description": "Premium Product B",
  "quantity": 100,
  "unit": "C62",
  "unit_price": 50.00,
  "tax_rate": "21.00",
  "allowances": [
    {
      "amount": 500.00,
      "reason": "Bulk discount (10%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}
```

**Calculation**:

* Base: 100 × €50 = €5,000.00
* Discount: -€500.00
* Amount: €4,500.00
* Tax: €4,500 × 21% = €945.00
* **Total**: €5,445.00

### Line Item with Charge

Product with special handling fee:

```json theme={null}
{
  "description": "Fragile Equipment",
  "quantity": 1,
  "unit": "C62",
  "unit_price": 500.00,
  "tax_rate": "21.00",
  "charges": [
    {
      "amount": 50.00,
      "reason": "Special handling - fragile item",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}
```

**Calculation**:

* Base: 1 × €500 = €500.00
* Handling: +€50.00
* Amount: €550.00
* Tax: €550 × 21% = €115.50
* **Total**: €665.50

### Mixed Products Invoice

Multiple line items with different rates:

```json theme={null}
{
  "items": [
    {
      "description": "Standard Product",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00"
    },
    {
      "description": "Reduced Rate Product (Books)",
      "quantity": 5,
      "unit": "C62",
      "unit_price": 20.00,
      "tax_rate": "6.00"
    },
    {
      "description": "Export Item (Zero-rated)",
      "quantity": 3,
      "unit": "C62",
      "unit_price": 200.00,
      "tax_rate": "0.00"
    }
  ]
}
```

**Calculation**:

* Line 1: €1,000 + €210 (21% tax) = €1,210.00
* Line 2: €100 + €6 (6% tax) = €106.00
* Line 3: €600 + €0 (0% tax) = €600.00
* **Total**: €1,916.00

## Calculation Flow

Understanding how amounts are calculated:

1. **Base Amount**: `quantity × unit_price`
2. **Apply Allowances**: Subtract line-level allowances
3. **Apply Charges**: Add line-level charges
4. **Line Amount**: `base - allowances + charges`
5. **Tax**: `line_amount × (tax_rate / 100)`
6. **Line Total**: `line_amount + tax`

Example with all modifiers:

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

**Calculation**:

1. Base: 20 × €100 = €2,000.00
2. * Allowance: -€200.00
3. * Charge: +€50.00
4. \= Amount: €1,850.00
5. Tax (21%): €388.50
6. **Total**: €2,238.50

## Best Practices

<AccordionGroup>
  <Accordion title="Always Provide Descriptions">
    Clear descriptions help customers understand what they're paying for:

    ✓ Good:

    ```json theme={null}
    {
      "description": "Premium Consulting Services - Project XYZ - October 2024"
    }
    ```

    ✗ Poor:

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

  <Accordion title="Use Appropriate Units">
    Match the unit to what you're selling:

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

  <Accordion title="Tax Rates">
    `tax_rate` is a number (0–100). A string is also accepted for backward compatibility, but sending a number with 2 decimal places is preferred:

    ✓ Preferred:

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

    ✓ Also accepted:

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

  <Accordion title="Consistent Decimal Places">
    Use consistent decimal places:

    * Prices: up to 4 decimals (€100.0000)
    * Quantities: up to 4 decimals (10.5000)
    * Tax rates: 2 decimals (21.00)
  </Accordion>
</AccordionGroup>

## Related

* [Document Schema](/api-reference/schemas/document)
* [Creating Invoices Guide](/guides/creating-invoices)
* [Advanced Invoicing Guide](/guides/advanced-invoicing)