> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Invoicing

> Learn how to use allowances and charges at document and line item levels

## 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:

1. **Document level** - Apply to the entire invoice (e.g., early payment discount, handling fees)
2. **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

```json theme={null}
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-001",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "BE0848934496",
  "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:

```json theme={null}
{
  "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:

```javascript theme={null}
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

```json theme={null}
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-002",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "BE0848934496",
  "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

```json theme={null}
{
  "charges": [
    {
      "amount": 30.00,
      "reason": "Payment processing fee",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}
```

### Multiple Charges

```json theme={null}
{
  "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:

```json theme={null}
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-003",
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "BE0848934496",
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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": "BE1018265814",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "BE0848934496",
  "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

```javascript theme={null}
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: 'BE1018265814',
    vendor_address: 'Main Street 123, 1000 Brussels, Belgium',
    customer_name: 'Customer Company NV',
    customer_tax_id: 'BE0848934496',
    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.is_valid) {
      console.error('Validation failed:', validation.data.issues);
      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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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**

```xml theme={null}
<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**

```xml theme={null}
<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

```javascript theme={null}
// Step 1: Always validate BEFORE creating documents
const validationResult = await api.post('/api/validate/json', invoiceData);

if (!validationResult.data.is_valid) {
  // Check which fields are missing or incorrect
  console.error('Validation errors:', validationResult.data.issues);
  // 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

<AccordionGroup>
  <Accordion title="Use Clear Descriptions">
    Always provide clear reasons for allowances and charges:

    ✓ Good:

    ```json theme={null}
    {
      "reason": "Early payment discount (2% if paid within 10 days)"
    }
    ```

    ✗ Poor:

    ```json theme={null}
    {
      "reason": "Discount"
    }
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Calculate Carefully">
    When calculating percentage-based discounts, ensure accuracy:

    ```javascript theme={null}
    // 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
    ```
  </Accordion>

  <Accordion title="Match Tax Categories">
    Ensure allowances and charges use appropriate tax categories that match the items they apply to.
  </Accordion>

  <Accordion title="Document Payment Terms">
    When offering early payment discounts, document the terms clearly:

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Common Use Cases

### 1. Volume Discounts

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

### 4. Financial Charges

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Credit Notes" icon="file-invoice" href="/guides/credit-notes">
    Learn about credit notes with allowances
  </Card>

  <Card title="Creating Invoices" icon="receipt" href="/guides/creating-invoices">
    Review basic invoice creation
  </Card>

  <Card title="Validation Guide" icon="check-circle" href="/guides/validation">
    Test complex invoices during development
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all endpoints
  </Card>
</CardGroup>