Advanced Invoicing - e-invoice.be

Overview

Beyond basic invoicing, you may need to apply:

Allowances (discounts) - Reduce the invoice amount
Charges (fees) - Increase the invoice amount

These can be applied at two levels:

Document level - Apply to the entire invoice (e.g., early payment discount, handling fees)
Line item level - Apply to specific products/services (e.g., bulk discount on one product)

Document-Level Allowances

Document-level allowances reduce the total invoice amount after calculating line items.

Early Payment Discount Example

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-001",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "0208:0123456789",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "0208:0987654321",
  "customer_address": "Customer Lane 456, 2000 Antwerp, Belgium",
  "items": [
    {
      "description": "Product A",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00"
    }
  ],
  "allowances": [
    {
      "amount": 50.00,
      "reason": "Early payment discount (5%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line items subtotal: €1,000.00
Allowance (discount): -€50.00
Net amount: €950.00
VAT (21%): €199.50
Total: €1,149.50

Multiple Document-Level Allowances

You can apply multiple allowances:

{
  "allowances": [
    {
      "amount": 50.00,
      "reason": "Volume discount",
      "tax_code": "S",
      "tax_rate": "21.00"
    },
    {
      "amount": 25.00,
      "reason": "Promotional discount",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line items subtotal: €1,000.00
Volume discount: -€50.00
Promotional discount: -€25.00
Net amount: €925.00
VAT (21%): €194.25
Total: €1,119.25

Percentage-Based Allowances

While the API accepts fixed amounts, you can calculate percentages in your code:

const lineItemsTotal = 1000.00;
const discountPercent = 5;
const discountAmount = lineItemsTotal * (discountPercent / 100);

const invoiceData = {
  // ... other fields
  allowances: [
    {
      amount: discountAmount,  // 50.00
      reason: `Early payment discount (${discountPercent}%)`,
      tax_code: 'S',
      tax_rate: '21.00'
    }
  ]
};

Document-Level Charges

Document-level charges increase the total invoice amount.

Shipping Fee Example

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-002",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "0208:0123456789",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "0208:0987654321",
  "customer_address": "Customer Lane 456, 2000 Antwerp, Belgium",
  "items": [
    {
      "description": "Product B",
      "quantity": 5,
      "unit": "C62",
      "unit_price": 200.00,
      "tax_rate": "21.00"
    }
  ],
  "charges": [
    {
      "amount": 25.00,
      "reason": "Shipping and handling",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line items subtotal: €1,000.00
Shipping charge: +€25.00
Net amount: €1,025.00
VAT (21%): €215.25
Total: €1,240.25

Financial Charges

{
  "charges": [
    {
      "amount": 30.00,
      "reason": "Payment processing fee",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Multiple Charges

{
  "charges": [
    {
      "amount": 25.00,
      "reason": "Shipping",
      "tax_code": "S",
      "tax_rate": "21.00"
    },
    {
      "amount": 15.00,
      "reason": "Insurance",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Combining Allowances and Charges

You can use both allowances and charges on the same invoice:

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-003",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "0208:0123456789",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "0208:0987654321",
  "customer_address": "Customer Lane 456, 2000 Antwerp, Belgium",
  "items": [
    {
      "description": "Product C",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00"
    }
  ],
  "allowances": [
    {
      "amount": 100.00,
      "reason": "Bulk purchase discount (10%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ],
  "charges": [
    {
      "amount": 30.00,
      "reason": "Express delivery",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line items subtotal: €1,000.00
Bulk discount: -€100.00
Express delivery: +€30.00
Net amount: €930.00
VAT (21%): €195.30
Total: €1,125.30

Line Item Level Allowances

Line item allowances apply to specific products/services.

Product-Specific Discount

{
  "items": [
    {
      "description": "Product D",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00",
      "allowances": [
        {
          "amount": 100.00,
          "reason": "10% discount on this product",
          "tax_code": "S",
          "tax_rate": "21.00"
        }
      ]
    },
    {
      "description": "Product E",
      "quantity": 5,
      "unit": "C62",
      "unit_price": 50.00,
      "tax_rate": "21.00"
    }
  ]
}

Calculation:

Line 1: (10 × €100) - €100 = €900.00
Line 2: 5 × €50 = €250.00
Subtotal: €1,150.00
VAT (21%): €241.50
Total: €1,391.50

Multiple Allowances on One Line Item

{
  "items": [
    {
      "description": "Product F",
      "quantity": 20,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00",
      "allowances": [
        {
          "amount": 100.00,
          "reason": "Volume discount (5%)",
          "tax_code": "S",
          "tax_rate": "21.00"
        },
        {
          "amount": 50.00,
          "reason": "Loyalty program discount",
          "tax_code": "S",
          "tax_rate": "21.00"
        }
      ]
    }
  ]
}

Line 1 Calculation:

Base: 20 × €100 = €2,000.00
Volume discount: -€100.00
Loyalty discount: -€50.00
Line total: €1,850.00

Line Item Level Charges

Apply charges to specific line items:

Special Handling Fee

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

Line 1 Calculation:

Base: 1 × €500 = €500.00
Special handling: +€50.00
Line total: €550.00

Complex Invoice Example

Here’s a complete invoice using allowances and charges at both levels:

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-100",
  "invoice_date": "2024-10-24",
  "due_date": "2024-11-24",
  "currency": "EUR",
  "payment_term": "Net 30 days - 2% discount if paid within 10 days",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "0208:0123456789",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "0208:0987654321",
  "customer_address": "Customer Lane 456, 2000 Antwerp, Belgium",
  "items": [
    {
      "description": "Premium Product A",
      "quantity": 20,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00",
      "allowances": [
        {
          "amount": 200.00,
          "reason": "Bulk discount (10%)",
          "tax_code": "S",
          "tax_rate": "21.00"
        }
      ]
    },
    {
      "description": "Standard Product B",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 50.00,
      "tax_rate": "21.00"
    },
    {
      "description": "Heavy Equipment",
      "quantity": 1,
      "unit": "C62",
      "unit_price": 1000.00,
      "tax_rate": "21.00",
      "charges": [
        {
          "amount": 100.00,
          "reason": "Oversized item handling",
          "tax_code": "S",
          "tax_rate": "21.00"
        }
      ]
    }
  ],
  "allowances": [
    {
      "amount": 150.00,
      "reason": "Early payment discount (5%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ],
  "charges": [
    {
      "amount": 50.00,
      "reason": "Delivery service",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Detailed Calculation: Line Items:

Line 1: (20 × €100) - €200 (bulk) = €1,800.00
Line 2: 10 × €50 = €500.00
Line 3: €1,000 + €100 (handling) = €1,100.00
Line items subtotal: €3,400.00

Document Level:

Early payment allowance: -€150.00
Delivery charge: +€50.00
Net amount: €3,300.00

Tax:

VAT (21% on €3,300): €693.00

Total: €3,993.00

Complete Code Example

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.e-invoice.be',
  headers: {
    'Authorization': `Bearer ${process.env.E_INVOICE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

async function createAdvancedInvoice() {
  const invoiceData = {
    document_type: 'INVOICE',
    invoice_id: 'INV-2024-100',
    invoice_date: '2024-10-24',
    due_date: '2024-11-24',
    currency: 'EUR',
    payment_term: 'Net 30 days - 2% discount if paid within 10 days',
    vendor_name: 'Your Company BVBA',
    vendor_tax_id: '0208:0123456789',
    vendor_address: 'Main Street 123, 1000 Brussels, Belgium',
    customer_name: 'Customer Company NV',
    customer_tax_id: '0208:0987654321',
    customer_address: 'Customer Lane 456, 2000 Antwerp, Belgium',
    items: [
      {
        description: 'Premium Product A',
        quantity: 20,
        unit: 'C62',
        unit_price: 100.00,
        tax_rate: '21.00',
        allowances: [
          {
            amount: 200.00,
            reason: 'Bulk discount (10%)',
            tax_code: 'S',
            tax_rate: '21.00'
          }
        ]
      },
      {
        description: 'Standard Product B',
        quantity: 10,
        unit: 'C62',
        unit_price: 50.00,
        tax_rate: '21.00'
      }
    ],
    allowances: [
      {
        amount: 150.00,
        reason: 'Early payment discount',
        tax_code: 'S',
        tax_rate: '21.00'
      }
    ],
    charges: [
      {
        amount: 50.00,
        reason: 'Delivery service',
        tax_code: 'S',
        tax_rate: '21.00'
      }
    ]
  };

  try {
    // 1. Validate
    console.log('Validating invoice...');
    const validation = await api.post('/api/validate/json', invoiceData);

    if (!validation.data.valid) {
      console.error('Validation failed:', validation.data.errors);
      return;
    }

    console.log('✓ Invoice validated');

    // 2. Create
    console.log('Creating invoice...');
    const invoice = await api.post('/api/documents/', invoiceData);
    console.log('✓ Invoice created:', invoice.data.id);

    // 3. Send
    console.log('Sending invoice...');
    const result = await api.post(`/api/documents/${invoice.data.id}/send`);
    console.log('✓ Invoice sent:', result.data.state);

  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createAdvancedInvoice();

Tax Considerations

Same Tax Rate

Allowances and charges typically use the same tax rate as the line items:

{
  "items": [
    {
      "tax_rate": "21.00"
    }
  ],
  "allowances": [
    {
      "tax_rate": "21.00",  // Match line items
      "tax_code": "S"
    }
  ]
}

Different Tax Rates

If your invoice has multiple tax rates, specify the appropriate rate for each allowance/charge:

{
  "items": [
    {
      "description": "Standard rate item",
      "unit_price": 100.00,
      "tax_rate": "21.00"
    },
    {
      "description": "Reduced rate item",
      "unit_price": 50.00,
      "tax_rate": "6.00"
    }
  ],
  "allowances": [
    {
      "amount": 50.00,
      "reason": "General discount on standard rate items",
      "tax_rate": "21.00",
      "tax_code": "S"
    }
  ]
}

Tax-Exempt Allowances/Charges

For tax-exempt items:

{
  "allowances": [
    {
      "amount": 100.00,
      "reason": "Discount on exempt items",
      "tax_rate": "0.00",
      "tax_code": "E"
    }
  ]
}

Context-Specific UBL Requirements

UBL (Universal Business Language) compliance depends on the context of your invoice. Depending on who the vendor is and the jurisdiction, UBL requires different fields to be present for the document to be valid. This is why validation is critical before document creation.

Why Validation Matters

Consider two similar invoice structures: Example 1: Valid UBL Document

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:eb3="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance/">
  <!-- Valid UBL structure with all required fields for this vendor context -->
</soapenv:Envelope>

This document passes validation because all required fields for this particular vendor and jurisdiction are present. Example 2: Invalid UBL Document

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:eb3="http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance/">
  <!-- Missing context-specific required fields -->
</soapenv:Envelope>

This document fails validation because certain fields required by UBL BIS Billing 3.0 for this vendor context are missing.

Context-Dependent Fields

What makes an invoice “valid” depends on:

Vendor jurisdiction - Different countries have different requirements
Vendor business type - Public sector, private company, non-profit, etc.
Invoice type - Regular invoice, credit note, etc.
Customer type - B2B, B2G, B2C, etc.
Tax obligations - VAT, reverse charge, exemptions, etc.

The e-invoice.be API automatically converts your JSON to UBL BIS Billing 3.0 XML. Always validate before creating documents to ensure your JSON structure will convert to a valid UBL document for your specific context.

Best Practice: Validate First

// Step 1: Always validate BEFORE creating documents
const validationResult = await api.post('/api/validate/json', invoiceData);

if (!validationResult.data.valid) {
  // Check which fields are missing or incorrect
  console.error('Validation errors:', validationResult.data.errors);
  // Fix the data based on validation feedback
  return;
}

// Step 2: Only after validation passes, create the document
const invoiceResult = await api.post('/api/documents/', invoiceData);

The validation endpoint checks:

✓ JSON structure matches API schema
✓ All required fields for your vendor context are present
✓ The JSON can be converted to valid UBL BIS Billing 3.0
✓ Tax codes and rates are compatible
✓ Amounts and calculations are correct

Never skip validation. It catches issues early and prevents failed document transmissions.

Best Practices

Use Clear Descriptions

Always provide clear reasons for allowances and charges:✓ Good:

{
  "reason": "Early payment discount (2% if paid within 10 days)"
}

✗ Poor:

{
  "reason": "Discount"
}

Choose the Right Level

Document level: When the allowance/charge applies to the entire order

Early payment discounts
Shipping for the entire order
Order-wide promotional discounts

Line item level: When it’s specific to a product

Bulk discount on one specific product
Special handling for fragile items
Product-specific promotions

Calculate Carefully

When calculating percentage-based discounts, ensure accuracy:

// Calculate discount based on line items total
const lineItemsTotal = calculateLineItemsTotal(invoice.items);
const discountPercent = 5;
const discountAmount = Math.round(
  lineItemsTotal * (discountPercent / 100) * 100
) / 100;  // Round to 2 decimal places

Match Tax Categories

Ensure allowances and charges use appropriate tax categories that match the items they apply to.

Document Payment Terms

When offering early payment discounts, document the terms clearly:

{
  "payment_term": "Net 30 days. 2% discount if paid within 10 days.",
  "allowances": [
    {
      "amount": 50.00,
      "reason": "Early payment discount (2%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Common Use Cases

1. Volume Discounts

{
  "items": [
    {
      "description": "Product X",
      "quantity": 100,
      "unit": "C62",
      "unit_price": 10.00,
      "tax_rate": "21.00",
      "allowances": [
        {
          "amount": 100.00,
          "reason": "Volume discount - 100+ units (10%)",
          "tax_code": "S",
          "tax_rate": "21.00"
        }
      ]
    }
  ]
}

2. Shipping and Handling

{
  "charges": [
    {
      "amount": 15.00,
      "reason": "Standard shipping",
      "tax_code": "S",
      "tax_rate": "21.00"
    },
    {
      "amount": 5.00,
      "reason": "Handling fee",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

3. Loyalty Program Discounts

{
  "allowances": [
    {
      "amount": 25.00,
      "reason": "Gold member discount (5%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

4. Financial Charges

{
  "charges": [
    {
      "amount": 2.50,
      "reason": "Credit card processing fee (2.5%)",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

Next Steps

Creating Credit Notes

Learn about credit notes with allowances

Creating Invoices

Review basic invoice creation

Validation Guide

Test complex invoices during development

API Reference

Explore all endpoints

Getting started

Core guides

Alternative formats

Integration

Partners

​Overview

​Document-Level Allowances

​Early Payment Discount Example

​Multiple Document-Level Allowances

​Percentage-Based Allowances

​Document-Level Charges

​Shipping Fee Example

​Financial Charges

​Multiple Charges

​Combining Allowances and Charges

​Line Item Level Allowances

​Product-Specific Discount

​Multiple Allowances on One Line Item

​Line Item Level Charges

​Special Handling Fee

​Complex Invoice Example

​Complete Code Example

​Tax Considerations

​Same Tax Rate

​Different Tax Rates

​Tax-Exempt Allowances/Charges

​Context-Specific UBL Requirements

​Why Validation Matters

​Context-Dependent Fields

​Best Practice: Validate First

​Best Practices

​Common Use Cases

​1. Volume Discounts

​2. Shipping and Handling

​3. Loyalty Program Discounts

​4. Financial Charges

​Next Steps

Creating Credit Notes

Creating Invoices

Validation Guide

API Reference

Overview

Document-Level Allowances

Early Payment Discount Example

Multiple Document-Level Allowances

Percentage-Based Allowances

Document-Level Charges

Shipping Fee Example

Financial Charges

Multiple Charges

Combining Allowances and Charges

Line Item Level Allowances

Product-Specific Discount

Multiple Allowances on One Line Item

Line Item Level Charges

Special Handling Fee

Complex Invoice Example

Complete Code Example

Tax Considerations

Same Tax Rate

Different Tax Rates

Tax-Exempt Allowances/Charges

Context-Specific UBL Requirements

Why Validation Matters

Context-Dependent Fields

Best Practice: Validate First

Best Practices

Common Use Cases

1. Volume Discounts

2. Shipping and Handling

3. Loyalty Program Discounts

4. Financial Charges

Next Steps