Skip to main content

​
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

​
description
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"
​
product_code
string
Product code or SKUInternal reference code for the product/service.Example: "PROD-001", "SKU-PREMIUM-A"

​
Quantity and Unit

​
quantity
number
Quantity of items (max 4 decimal places)Example: 10, 2.5, 100.0
​
unit
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

​
unit_price
number
Price per unit (max 2 decimal places), excluding VATThis is the price for a single unit before any allowances or charges.Example: 100.00, 50.99, 1250.00
​
amount
number
Total line amount (max 2 decimal places), excluding VATTotal amount for this line item after subtracting allowances and adding charges:Calculation: (quantity × unit_price) - allowances + chargesIf not provided, automatically calculated from quantity, unit_price, allowances, and charges.Example: 1000.00, 950.00 (after €50 discount)

​
Tax

​
tax_rate
string
VAT/tax rate as a percentage string with 2 decimal placesFormat: "XX.XX"Common Belgian rates:
  • "21.00" - Standard rate
  • "6.00" - Reduced rate
  • "0.00" - Zero-rated
Example: "21.00", "6.00", "0.00"
​
tax
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)

​
allowances
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)

​
charges
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:
  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: 
{
  "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
    • Allowance: -€200.00
    • Charge: +€50.00
  4. = Amount: €1,850.00
  5. Tax (21%): €388.50
  6. Total: €2,238.50

​
Best Practices

Clear descriptions help customers understand what they’re paying for:✓ Good:
{
  "description": "Premium Consulting Services - Project XYZ - October 2024"
}
✗ Poor:
{
  "description": "Services"
}
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)
Always use string format with 2 decimal places:✓ Correct:
{
  "tax_rate": "21.00"
}
✗ Wrong:
{
  "tax_rate": 21
}
Use consistent decimal places:
  • Prices: 2 decimals (€100.00)
  • Quantities: up to 4 decimals (10.5000)
  • Tax rates: exactly 2 decimals as string (“21.00”)