Skip to main content

​
Overview

The AllowanceCharge class represents either an allowance (discount) or a charge (surcharge) that can be applied at the document level or line level in UBL documents. This component is essential for representing price adjustments, discounts, handling fees, shipping charges, and other modifications to base amounts.

​
Class Definition

import { AllowanceCharge } from 'ubl-builder/lib/ubl21/CommonAggregateComponents';

​
Constructor Parameters

​
chargeIndicator
boolean | UdtIndicator
required
An indicator that this AllowanceCharge describes a charge (true) or a discount/allowance (false)
​
allowanceChargeReasonCode
string | UdtCode
required
A mutually agreed code signifying the reason for this allowance or charge
​
allowanceChargeReason
string | UdtText
required
The reason for this allowance or charge, expressed as text
​
amount
string | UdtAmount
required
The monetary amount of this allowance or charge to be applied
​
taxCategory
TaxCategory
required
A tax category applicable to this allowance or charge
​
id
string | UdtIdentifier
An identifier for this allowance or charge
​
baseAmount
string | UdtAmount
The monetary amount to which the multiplier factor is applied in calculating the amount of this allowance or charge

​
Common Reason Codes

​
Allowance (Discount) Codes

  • 41 - Bonus for works ahead of schedule
  • 42 - Other bonus
  • 60 - Manufacturer’s consumer discount
  • 62 - Due to military status
  • 63 - Due to work accident
  • 64 - Special agreement
  • 65 - Production error discount
  • 66 - New outlet discount
  • 67 - Sample discount
  • 68 - End-of-range discount
  • 95 - Discount

​
Charge (Surcharge) Codes

  • AA - Advertising
  • AAA - Telecommunication
  • ABL - Additional packaging
  • ADR - Other services
  • AEO - Pick-up
  • FC - Freight service
  • FI - Financing
  • LA - Labelling
  • PC - Packing
  • SH - Shipping and handling

​
Usage Examples

import { 
  AllowanceCharge,
  TaxCategory,
  TaxScheme
} from 'ubl-builder/lib/ubl21/CommonAggregateComponents';

const taxCategory = new TaxCategory({
  id: 'S',
  percent: '21',
  taxScheme: new TaxScheme({ id: 'VAT' })
});

const discount = new AllowanceCharge({
  chargeIndicator: false, // false = allowance/discount
  allowanceChargeReasonCode: '95',
  allowanceChargeReason: 'Volume discount',
  amount: '100.00',
  baseAmount: '1000.00',
  taxCategory: taxCategory
});
Important: Set chargeIndicator to false for discounts/allowances (reduces the total) and true for charges/surcharges (increases the total). This is a common source of errors.

​
Calculation Impact

Allowances and charges affect invoice totals as follows:

​
Document-Level Calculation

Line Extension Amount (sum of all lines)
- Document-level Allowances
+ Document-level Charges
= Tax Exclusive Amount
+ Tax Amount
= Tax Inclusive Amount (Payable Amount)

​
Line-Level Calculation

(Quantity × Price)
- Line-level Allowances
+ Line-level Charges
= Line Extension Amount

​
Exported Aliases

The AllowanceCharge class may also be exported as:
  • ExtraAllowanceCharge
  • FreightAllowanceCharge
  • ServiceAllowanceCharge
These aliases provide semantic meaning based on usage context.
  • TaxTotal - Taxes may apply to allowances/charges
  • TaxCategory - Tax treatment of the allowance/charge
  • Invoice - Document-level allowances/charges
  • InvoiceLine - Line-level allowances/charges
  • LegalMonetaryTotal - Reflects impact of allowances/charges

​
Best Practices

  1. Indicator Value: Always double-check the chargeIndicator value (false for discounts, true for charges)
  2. Reason Codes: Use standard UNCL 5189 and UNCL 7161 codes for interoperability
  3. Base Amount: Include baseAmount when applying percentage-based adjustments
  4. Tax Treatment: Ensure allowances/charges have appropriate tax categories
  5. Clear Descriptions: Provide clear allowanceChargeReason text for transparency
  6. Level Placement: Use document-level for global adjustments, line-level for item-specific adjustments

​
UBL Schema Reference

For more information, see the UBL 2.1 AllowanceCharge specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us