# BR-CO-21 Document allowance needs a reason or reason code

Each document level allowance (BG-20) shall contain a document level allowance reason (BT-97) or a document level allowance reason code (BT-98), or both.

## Problem Description

> **ERROR**: EN 16931 calculation and consistency rule (BR-CO)

## Context and Significance

This EN 16931 rule requires every document level allowance to state why it is granted, as text or as a code, so that the buyer can understand and book the deduction. The error often occurs when the ERP exports only an allowance amount or percentage without a description, for example a global discount entered as a plain amount.

## Solution

For every document level allowance, add a reason (BT-97) and/or a reason code (BT-98) from UNCL 5189: cbc:AllowanceChargeReason / cbc:AllowanceChargeReasonCode in UBL, ram:Reason / ram:ReasonCode in ram:SpecifiedTradeAllowanceCharge in CII.

- [Validate XML](/en/xrechnung-validator?source=resource&rule=BR-CO-21)
- [Convert invoice](/en/pdf-to-xrechnung?source=resource&rule=BR-CO-21)

## Valid Examples

- Document allowance with BT-98 = 95 and BT-97 = "Volume discount"

## Invalid Examples

- Document allowance amount 10.00 with neither BT-97 nor BT-98

## Code Examples

### Valid XML
```
<cac:AllowanceCharge>
  <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
  <cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
  <cbc:AllowanceChargeReason>Volume discount</cbc:AllowanceChargeReason>
  <cbc:Amount currencyID="EUR">10.00</cbc:Amount>
  <cac:TaxCategory>
    <cbc:ID>S</cbc:ID>
    <cbc:Percent>19</cbc:Percent>
    <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
  </cac:TaxCategory>
</cac:AllowanceCharge>
```

### Invalid XML
```
<cac:AllowanceCharge>
  <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
  <cbc:Amount currencyID="EUR">10.00</cbc:Amount>
  <cac:TaxCategory>
    <cbc:ID>S</cbc:ID>
    <cbc:Percent>19</cbc:Percent>
    <cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme>
  </cac:TaxCategory>
</cac:AllowanceCharge>
```

## Affected Fields

- [BG-20 Document level allowances](/resources/xrechnung/bt-92-document-level-allowance-amount)
- [BT-97 Document level allowance reason](/resources/xrechnung/bt-97-document-level-allowance-reason)
- [BT-98 Document level allowance reason code](/resources/xrechnung/bt-98-document-level-allowance-reason-code)

## Related Rules

- [BR-CO-05](/resources/kosit-validator-errors/br-co-05-allowance-reason-code-match)
- [BR-CO-22](/resources/kosit-validator-errors/br-co-22-document-charge-reason-required)
- [BR-CO-23](/resources/kosit-validator-errors/br-co-23-line-allowance-reason-required)

## Validation Tools

- [Official KoSIT Validator](https://github.com/itplr-kosit/validator): Run the official KoSIT validator with the XRechnung configuration to check EN 16931 and XRechnung rules.
- [Convert PDF to XRechnung](/pdf-to-xrechnung): Find validation errors during conversion and review each correction.

## Related Resources

- [Official Specification](https://docs.peppol.eu/poacc/billing/3.0/rules/ubl-tc434/)
- [Test Suite](https://github.com/itplr-kosit/xrechnung-testsuite)
- [All validation errors](/resources/kosit-validator-errors): Overview of the EN 16931, XRechnung and Peppol validation rules explained here.