LineItem

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.

All fields are optional, but providing description, quantity, unit_price, and tax_rate creates complete, clear line items.

Basic Fields

string

Description of the product or serviceThis is the primary field for identifying what is being sold.Example: "Professional Services", "Product A - Premium Edition", "Consulting hours - October 2024"

string

Product code or SKUInternal reference code for the product/service.Example: "PROD-001", "SKU-PREMIUM-A"

Quantity and Unit

number

Quantity of items (max 4 decimal places)Example: 10, 2.5, 100.0

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"

Pricing

number

Price per unit (max 4 decimal places), excluding VATThis is the price for a single unit before any allowances or charges.Example: 100.00, 50.99, 1250.00

number

Total line amount (max 2 decimal places), excluding VATTotal 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 + chargesProvide 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)

Tax

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

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)

Allowances (Discounts)

array

Line-level allowances (discounts) applied to this specific itemUse for product-specific discounts (bulk discounts, promotions, etc.)Example:

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

See Advanced Invoicing guide for details.

Charges (Fees)

array

Line-level charges (fees) applied to this specific itemUse for product-specific fees (special handling, customization fees, etc.)Example:

[
  {
    "amount": 50.00,
    "reason": "Special handling - fragile item",
    "tax_code": "S",
    "tax_rate": "21.00"
  }
]

See Advanced Invoicing guide for details.

Examples

Simple Line Item

Basic product line:

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

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

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

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

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

Base Amount: quantity × unit_price
Apply Allowances: Subtract line-level allowances
Apply Charges: Add line-level charges
Line Amount: base - allowances + charges
Tax: line_amount × (tax_rate / 100)
Line Total: line_amount + tax

Example with all modifiers:

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

Base: 20 × €100 = €2,000.00
- Allowance: -€200.00
- Charge: +€50.00
= Amount: €1,850.00
Tax (21%): €388.50
Total: €2,238.50

Best Practices

Always Provide Descriptions

Clear descriptions help customers understand what they’re paying for:✓ Good:

{
  "description": "Premium Consulting Services - Project XYZ - October 2024"
}

✗ Poor:

{
  "description": "Services"
}

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)

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:

{
  "tax_rate": 21.00
}

✓ Also accepted:

{
  "tax_rate": "21.00"
}

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)

Documents

Inbox

Mailbox

Outbox

Drafts

Validate

Lookup

Tenant

Webhooks

Conversion

Overview

Basic Fields

Quantity and Unit

Pricing

Tax

Allowances (Discounts)

Charges (Fees)

Examples

Simple Line Item

Service Line Item

Line Item with Discount

Line Item with Charge

Mixed Products Invoice

Calculation Flow

Best Practices

​Overview

​Basic Fields

​Quantity and Unit

​Pricing

​Tax

​Allowances (Discounts)

​Charges (Fees)

​Examples

​Simple Line Item

​Service Line Item

​Line Item with Discount

​Line Item with Charge

​Mixed Products Invoice

​Calculation Flow

​Best Practices

​Related

Overview

Basic Fields

Quantity and Unit

Pricing

Tax

Allowances (Discounts)

Charges (Fees)

Examples

Simple Line Item

Service Line Item

Line Item with Discount

Line Item with Charge

Mixed Products Invoice

Calculation Flow

Best Practices

Related