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. For a complete line, send description, quantity, unit, unit_price, amount and tax_rate.

Basic fields

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"

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
KWH - Kilowatt hours

Example: "HUR"

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

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).

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 + chargesSend 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

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, the API calculates it from amount and tax_rate.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
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