LineItem

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.

All fields are optional in the schema. But a line without description (or name) fails rule BR-25, and a line without quantity or unit_price counts as 0.00 in the totals. For a complete line, send description, quantity, unit, unit_price, amount and tax_rate.

Basic fields

string

Description of the product or service (BT-154). The API writes it to cac:Item/cbc:Description. When name is absent, the API also writes it as the item name.Example: "Consulting hours - September 2026"

string

Name of the item (BT-153), for example the product name. The API writes it to cac:Item/cbc:Name. When it is absent, the API uses description as the item name.Example: "Wireless mouse"

string

Product code or SKU of the seller. The API writes it to cac:Item/cac:SellersItemIdentification/cbc:ID.Example: "PROD-001"

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

Quantity and unit

number

Quantity of items, with a maximum of 4 decimals. It can be negative for credit notes or corrections.Example: 10, 2.5

enum

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

Example: "HUR"The API accepts only the codes of its UnitOfMeasureCode list (see the API reference). A code that is not in the list, for example KWH, gives 422. When unit is absent, the API uses NAR (number of articles).

Pricing

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

number

default:"1"

Number of units to which unit_price applies (BT-149), for example 100 when the price is the price of 100 units. Must be more than 0. The API writes it to cac:Price/cbc:BaseQuantity.Example: 1, 100

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 / price_base_quantity) - allowances + chargesThe API writes amount to the UBL as the line extension amount and uses it for the tax breakdown. The totals check uses quantity, unit_price, price_base_quantity and the line allowances and charges. It can be negative for credit notes or corrections.When amount is absent, the API sets it to quantity × unit_price / price_base_quantity, without the line allowances and charges. Thus, when a line has allowances or charges, you must send amount. If not, the UBL fails rule PEPPOL-EN16931-R120 and the API returns 406.Example: 1000.00

Tax

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

number

VAT amount of the line, with a maximum of 2 decimals.Calculation: amount × (tax_rate / 100)When it is absent and you send amount, the API calculates it from amount and tax_rate. The value is for information only: the API does not write it to the UBL and does not use it for total_tax.Example: 210.00 (21% of 1000.00)

Item attributes

array

Properties of the item, such as colour or size (BG-32). The API writes each attribute to cac:Item/cac:AdditionalItemProperty.

Show properties

string

required

Name of the attribute (BT-160).Example: "Colour"

string

Value of the attribute (BT-161). The API does not write an attribute without a value to the UBL.Example: "Blue"

Example:

[
  { "name": "Colour", "value": "Blue" },
  { "name": "Size", "value": "XL" }
]

Allowances and charges

array

Line-level allowances (discounts) for this item only, for example a bulk discount or a promotion.

Show properties

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

string

Reason for the allowance as text.Example: "Bulk discount"

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)

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

number

Amount to which the percentage applies, with a maximum of 2 decimals. Send it together with multiplier_factor.Example: 5000.00

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.

number

default:"21.00"

VAT rate as a percentage. The API does not write it on a line-level allowance in the UBL.

Example of a 10% allowance:

[
  {
    "reason": "Bulk discount",
    "reason_code": "95",
    "multiplier_factor": 10,
    "base_amount": 5000.00,
    "amount": 500.00
  }
]

array

Line-level charges (fees) for this item only, for example special handling or customisation.

Show properties

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

string

Reason for the charge as text.Example: "Additional packaging"

enum

Charge reason code (UNCL7161). The full list of permitted values is in the ChargeReasonCode schema of the API reference.Example: "ABL" (additional packaging)

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

number

Amount to which the percentage applies, with a maximum of 2 decimals. Send it together with multiplier_factor.Example: 500.00

enum

default:"S"

VAT category code. The API does not write a tax category on a line-level charge in the UBL.

number

default:"21.00"

VAT rate as a percentage. The API does not write it on a line-level charge in the UBL.

Example:

[
  {
    "reason": "Additional packaging",
    "reason_code": "ABL",
    "amount": 50.00
  }
]

See Advanced invoicing for document-level allowances and charges and their effect on the totals.

Examples

Simple line item

{
  "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

{
  "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

{
  "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:

<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

{
  "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

{
  "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

{
  "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

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

Example with an allowance and a charge:

{
  "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"
    }
  ]
}

Base: 20 × 100.00 = 2000.00
Allowance: 200.00
Charge: 50.00
Amount: 1850.00
Tax (21%): 388.50

In the document totals, the API calculates VAT for each tax group (tax category and rate), not for each line. See Normalisation and rounding.

Best practices

Write a specific description

A specific description tells the customer what the line is for.Recommended:

{
  "description": "Consulting services - Project XYZ - September 2026"
}

Not recommended:

{
  "description": "Services"
}

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)

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:

{
  "tax_rate": 21.00
}

Also accepted:

{
  "tax_rate": "21.00"
}

Stay within the decimal limits

Unit prices: a maximum of 4 decimals
Quantities: a maximum of 4 decimals
Amounts and tax rates: 2 decimals

Next Steps

Document

Look up the document fields and their conversion to UBL.

Advanced invoicing

Apply allowances and charges on the line and on the document.

Invoice totals and calculations

Calculate the totals from the line amounts.

Create e-invoices

Create and send an invoice with line items.

Overview

Schemas

Endpoints

Overview

Basic fields

Quantity and unit

Pricing

Tax

Item attributes

Allowances and charges

Examples

Simple line item

Service line item

Line item with item attributes

Line item with a percentage allowance

Line item with a charge

Lines with different tax rates

Calculation flow

Best practices

Next Steps

Document

Advanced invoicing

Invoice totals and calculations

Create e-invoices

​Overview

​Basic fields

​Quantity and unit

​Pricing

​Tax

​Item attributes

​Allowances and charges

​Examples

​Simple line item

​Service line item

​Line item with item attributes

​Line item with a percentage allowance

​Line item with a charge

​Lines with different tax rates

​Calculation flow

​Best practices

​Next Steps

Document

Advanced invoicing

Invoice totals and calculations

Create e-invoices

Overview

Basic fields

Quantity and unit

Pricing

Tax

Item attributes

Allowances and charges

Examples

Simple line item

Service line item

Line item with item attributes

Line item with a percentage allowance

Line item with a charge

Lines with different tax rates

Calculation flow

Best practices

Next Steps