Handles AllowanceCharge structures for UBL 2.1 invoices.

AllowanceCharge represents discounts (allowances) or surcharges (charges) that can be applied at two levels:

Document Level

Applied to the entire invoice. These MUST include a TaxCategory because they affect the overall tax calculation of the invoice.

Line Item Level

Applied to individual invoice lines. These SHOULD NOT include a TaxCategory because they inherit the tax settings from the line item they belong to.

Structure

Required Fields

• :charge_indicator - Boolean. false = Allowance/Discount, true = Charge/Surcharge
• :amount - Decimal string. The total amount of the allowance or charge

Optional Fields

• :allowance_charge_reason_code - Code identifying the reason (UNTDID 5189 for allowances, 7161 for charges)
• :allowance_charge_reason - Text description of the allowance or charge
• :multiplier_factor_numeric - Decimal. The percentage (e.g., 10 for 10%)
• :base_amount - Decimal string. The base amount the percentage is applied to

Document Level Only

• :tax_category - Required for document level. Contains:
  • :id - Tax category code (e.g., :standard_rate, :exempt, :outside_scope)
  • :percent - Tax percentage
  • :tax_scheme_id - Tax scheme identifier (e.g., :vat)
  • :tax_exemption_reason - (optional) Text reason for exemption (Croatian HR extension)
  • :tax_exemption_reason_code - (optional) Code for exemption reason (Croatian HR extension)

Croatian Extensions (Fiskalizacija 2.0)

For non-taxable document-level charges (e.g., "Povratna naknada" - deposit/return fee), the TaxCategory should use :outside_scope (O) or :exempt (E) with the appropriate exemption reason fields populated.

Examples

Document Level Charge (Shipping Fee with VAT)

%{
  charge_indicator: true,
  allowance_charge_reason_code: :freight,
  allowance_charge_reason: "Shipping and handling",
  amount: "15.00",
  tax_category: %{
    id: :standard_rate,
    percent: 25,
    tax_scheme_id: :vat
  }
}

Document Level Charge (Non-taxable Deposit Fee - Croatian)

%{
  charge_indicator: true,
  allowance_charge_reason_code: :deposit_fee,
  allowance_charge_reason: "Povratna naknada",
  amount: "0.50",
  tax_category: %{
    id: :outside_scope,
    percent: 0,
    tax_scheme_id: :vat,
    tax_exemption_reason: "Povratna naknada - Loss Pot"
  }
}

Document Level Discount (10% off total)

%{
  charge_indicator: false,
  allowance_charge_reason_code: :discount,
  allowance_charge_reason: "Loyalty discount",
  multiplier_factor_numeric: 10,
  base_amount: "100.00",
  amount: "10.00",
  tax_category: %{
    id: :standard_rate,
    percent: 25,
    tax_scheme_id: :vat
  }
}

Line Item Level Discount

%{
  charge_indicator: false,
  allowance_charge_reason_code: :discount,
  allowance_charge_reason: "Volume discount",
  multiplier_factor_numeric: 5,
  base_amount: "200.00",
  amount: "10.00"
}