Allowance and charge reason codes

A reason code says why a discount (an allowance) or an extra cost (a charge) was added to an invoice. GETS takes it in two fields:

• allowancesAndCharges[].reasonCode, for an allowance or charge on the whole document
• lineItems[].discountsOrCharges[].reasonCode, for an allowance or charge on one line

isCharge decides which list the code comes from. With isCharge: true the entry is a charge, and its reason comes from the charge reasons list (UNCL 7161). With isCharge: false it is an allowance, and its reason comes from the allowance reasons list (UNCL 5189). Put a description in your own words in reason.

What to send in each country

In the UAE, send the value, not the code. Complyance writes the matching code into the e-invoice for you. A code such as AA is rejected with IBR-CL-20 on a charge or IBR-CL-19 on an allowance. An allowance or charge whose taxCategory is E must have a reason code (IBR-168-AE, IBR-169-AE).

In every other country, the code goes into the e-invoice unchanged, so it must be a code from the list. In Saudi Arabia every document-level charge needs a reason code (BR-KSA-19), and a charge code outside the list returns the warning BR-KSA-CL-06. In Oman every document-level charge needs a reason code (IBR-042-OM).

"lineItems": [
  {
    "id": "1",
    "name": "Cloud subscription — Business plan",
    "quantity": 20,
    "unitCode": "PCE",
    "price": { "amount": 100, "grossPrice": 100 },
    "discountsOrCharges": [
      {
        "isCharge": true,
        "reasonCode": "rush_delivery",
        "reason": "Express shipping",
        "amount": 50
      }
    ],
    "lineTaxableValue": 2050,
    "taxCategory": "S",
    "taxRate": 5,
    "taxAmount": 102.5
  }
]

"discountsOrCharges": [
  {
    "isCharge": true,
    "reasonCode": "AAT",
    "reason": "Express shipping",
    "amount": 50
  }
]

A line charge is part of the line’s net amount, so lineTaxableValue (here 20 × 100 + 50) and the line’s tax include it, and so do the document totals. Use the tax category and rate that apply in each country; see the field reference.

Charge reasons

UNCL 7161, version D.16B. Use these when isCharge is true.

Allowance reasons

UNCL 5189, version D.16B. Use these when isCharge is false.

The UAE code lists page has both lists with their full descriptions, and a CSV download of each.