Invoice Schema

The invoice schema below is the NRS (National Revenue Service) standard required for FIRS e-invoicing compliance. All invoices submitted through the Heirs E-Invoicing Middleware must conform to this structure. Fields are organised into six sections.

---

Invoice Header

Field	Type	Max Length	Required	Description
business_id	String	36	Yes	Business UUID
irn	String	50	Yes	Invoice Reference Number
invoice_kind	String	3	Yes	Invoice nature: B2B, B2C, or B2G
issue_date	Date (YYYY-MM-DD)	10	Yes	Invoice issue date
due_date	Date (YYYY-MM-DD)	10	Yes	Invoice due date
issue_time	Time (HH:mm:ss)	8	Yes	Invoice issue time
invoice_type_code	String	10	Yes	Invoice type code
tax_point_date	Date (YYYY-MM-DD)	10	Yes	Tax point date
document_currency_code	String	3	Yes	Document currency
tax_currency_code	String	3	Yes	Tax currency
billing_reference[].irn	String	50	Credit notes only	Original invoice IRN
billing_reference[].issue_date	Date (YYYY-MM-DD)	10	Credit notes only	Original invoice issue date

---

Supplier Information (accounting_supplier_party)

Field	Type	Max Length	Required	Description
party_name	String	100	Yes	Supplier name
tin	String	20	Yes	Supplier TIN
email	String	100	Yes	Supplier email
telephone	String	20	Yes	Supplier phone
business_description	String	255	No	Business description
postal_address.street_name	String	150	Yes	Street name
postal_address.city_name	String	100	Yes	City
postal_address.postal_zone	String	20	No	Postal code
postal_address.country	String	2	Yes	Country code (ISO 3166-1 alpha-2)

---

Customer Information (accounting_customer_party)

Only included when a customer TIN is provided. Minimum TIN length is 5 characters.

Field	Type	Max Length	Required	Description
party_name	String	100	Yes	Customer name
tin	String	20	Yes	Customer TIN (min 5 characters)
email	String	100	Yes	Customer email
telephone	String	20	Yes	Customer phone
business_description	String	255	No	Business description
postal_address.street_name	String	150	No	Street name
postal_address.city_name	String	100	Yes	City
postal_address.postal_zone	String	20	No	Postal code
postal_address.country	String	2	Yes	Country code (ISO 3166-1 alpha-2)

---

Invoice Line Items (invoice_line[])

An array — one entry per product or service billed.

Field	Type	Required	Description
hsn_code	String	Yes	Product classification code
product_category	String	Yes	Product category
invoiced_quantity	Decimal	Yes	Quantity
line_extension_amount	Decimal	Yes	Line total amount
discount_rate	Decimal	No	Discount rate
discount_amount	Decimal	No	Discount amount
fee_rate	Decimal	No	Fee rate
fee_amount	Decimal	No	Fee amount
item.name	String	Yes	Item name
item.description	String	No	Item description
item.sellers_item_identification	String	Yes	Item ID
price.price_amount	Decimal	Yes	Unit price
price.base_quantity	Decimal	Yes	Base quantity
price.price_unit	String	Yes	Price unit

---

Tax Structure (tax_total[])

Field	Type	Required	Description
tax_amount	Decimal	Yes	Total tax amount
tax_subtotal[].taxable_amount	Decimal	Yes	Taxable amount
tax_subtotal[].tax_amount	Decimal	Yes	Tax amount for this category
tax_subtotal[].tax_category.id	String	Yes	Tax category (e.g. STANDARD_VAT, ZERO_VAT)
tax_subtotal[].tax_category.percent	Decimal	Yes	Tax rate (%)

---

Monetary Totals (legal_monetary_total)

Field	Type	Required	Description
line_extension_amount	Decimal	Yes	Sum of all line amounts
tax_exclusive_amount	Decimal	Yes	Total before tax
tax_inclusive_amount	Decimal	Yes	Total after tax
payable_amount	Decimal	Yes	Final payable amount