Invoice Payload Reference
This is the full field-by-field reference for the FIRS/UBL-style invoice document — the schema behind
Create Invoice (Full) on
the Taxpayer API. The Access Point Provider's
Submit Invoice and
Validate Invoice endpoints accept
the same document with a handful of differences, called out on their own pages.
1. Core invoice details
| Field |
Type |
Required |
Description |
| invoice_no |
string |
Yes
|
Your unique invoice number |
| invoice_category |
string |
Yes
|
B2B, B2C or B2G |
| irn |
string |
Yes
|
Invoice Reference Number, format {invoice_no}-{service_id}-{YYYYMMDD}. The service-id segment must match your account's firs_service_id |
| issue_date |
date |
Yes
|
Cannot be in the future |
| due_date |
date |
No
|
Must be on or after issue_date, if supplied |
| issue_time |
string |
No
|
HH:mm:ss |
| invoice_type_code |
string |
Yes
|
Must exist in Invoice Types |
| payment_status |
string |
No
|
PENDING, PAID, or CANCELLED — defaults to PENDING |
| note |
string |
No
|
Max 1000 characters. Encrypted at rest |
| tax_point_date |
date |
No
|
Date tax liability arises — defaults to issue_date |
| document_currency_code |
string (ISO-4217) |
Yes
|
Must exist in Currencies |
| tax_currency_code |
string (ISO-4217) |
No
|
Defaults to document_currency_code |
| accounting_cost |
number |
No
|
Internal accounting reference amount — defaults to 0 |
| buyer_reference |
string |
No
|
Buyer's internal reference, max 255 characters |
2. Invoice delivery period
| Field |
Type |
Required |
Description |
| invoice_delivery_period |
object |
No
|
Period covered by the invoice |
| invoice_delivery_period.start_date |
date |
No
|
Must be on or before end_date |
| invoice_delivery_period.end_date |
date |
No
|
Must be on or after start_date |
3. Document references
Used to reference related invoices or documents.
Billing reference (multiple)
| Field |
Type |
Required |
Description |
| billing_reference |
array |
No
|
|
| billing_reference[].irn |
string |
Conditional
|
Required if billing_reference is present |
| billing_reference[].issue_date |
date |
Conditional
|
Required if billing_reference is present |
Single document references (optional)
Each of the following is an optional object with the same two sub-fields:
dispatch_document_reference, receipt_document_reference,
originator_document_reference, contract_document_reference.
| Field |
Type |
Required |
Description |
| {reference}.irn |
string |
No
|
|
| {reference}.issue_date |
date |
No
|
|
Additional document references (multiple)
| Field |
Type |
Required |
Description |
| additional_document_reference |
array |
No
|
|
| additional_document_reference[].irn |
string |
Conditional
|
Required if additional_document_reference is present |
| additional_document_reference[].issue_date |
date |
Conditional
|
Required if additional_document_reference is present |
4. Accounting customer party (buyer)
| Field |
Type |
Required |
Description |
| accounting_customer_party |
object |
Yes
|
Buyer details |
| customer_no |
string |
Yes
|
Buyer customer number |
| party_name |
string |
Yes
|
Buyer legal name |
| tin |
string |
Conditional
|
Required when invoice_category is B2B |
| email |
string (email) |
Yes
|
Buyer email |
| telephone |
string |
No
|
Contact phone number |
| business_description |
string |
Conditional
|
Required when invoice_category is B2B or B2G — min 5 characters |
Postal address (required)
| Field |
Type |
Required |
Description |
| postal_address |
object |
Yes
|
|
| street_name |
string |
Yes
|
|
| city_name |
string |
Yes
|
|
| postal_zone |
string |
Yes
|
|
| country |
string (ISO-3166-1 alpha-2) |
Yes
|
|
5. Actual delivery date
| Field |
Type |
Required |
Description |
| actual_delivery_date |
date |
No
|
|
6. Payment means
| Field |
Type |
Required |
Description |
| payment_means |
array |
No
|
|
| payment_means[].payment_means_code |
string |
Conditional
|
Required if payment_means is present — must exist in Payment Means |
| payment_means[].payment_due_date |
date |
Conditional
|
Required if payment_means is present |
| payment_terms_note |
string |
No
|
Max 1000 characters |
7. Allowance / charge
| Field |
Type |
Required |
Description |
| allowance_charge |
array |
No
|
|
| allowance_charge[].charge_indicator |
boolean |
Conditional
|
Required if allowance_charge is present |
| allowance_charge[].amount |
number |
Conditional
|
Required if allowance_charge is present, min 0 |
8. Tax totals
| Field |
Type |
Required |
Description |
| tax_total |
array |
No
|
|
| tax_total[].tax_amount |
number |
No
|
Min 0 |
| tax_total[].tax_subtotal |
array |
No
|
|
| tax_subtotal[].taxable_amount |
number |
Conditional
|
Required if tax_subtotal is present |
| tax_subtotal[].tax_amount |
number |
Conditional
|
Required if tax_subtotal is present |
| tax_subtotal[].tax_category.id |
string |
Conditional
|
Required if tax_subtotal is present — must exist in Tax Categories |
| tax_subtotal[].tax_category.percent |
number |
Conditional
|
Required if tax_subtotal is present — 0 to 100 |
9. Legal monetary total (required)
| Field |
Type |
Required |
Description |
| legal_monetary_total |
object |
Yes
|
|
| line_extension_amount |
number |
Yes
|
Min 0.01. Must equal tax_exclusive_amount, and must equal the sum of every line's line_extension_amount |
| tax_exclusive_amount |
number |
Yes
|
Min 0 |
| tax_inclusive_amount |
number |
Yes
|
Min 0. Must be greater than or equal to tax_exclusive_amount |
| payable_amount |
number |
Yes
|
Min 0 |
10. Invoice lines (at least one required)
| Field |
Type |
Required |
Description |
| invoice_line |
array |
Yes
|
Minimum 1 |
| hsn_code |
string |
No
|
PRODUCT lines — format 9999.99 |
| isic_code |
string |
No
|
SERVICE lines — format 9999 |
| product_category |
string |
Conditional
|
Required when item.type is PRODUCT — format 9999.99, must exist in Product Codes |
| service_category |
string |
Conditional
|
Required when item.type is SERVICE — format 9999, must exist in Service Codes |
| discount_rate |
number |
No
|
0 to 100 |
| discount_amount |
number |
No
|
Min 0 |
| fee_rate |
number |
No
|
0 to 100 |
| fee_amount |
number |
No
|
Min 0 |
| invoiced_quantity |
number |
Yes
|
Min 0.01 |
| line_extension_amount |
number |
Yes
|
Min 0.01 |
| tax_category |
string |
Yes
|
Must exist in Tax Categories |
| total_tax |
number |
Yes
|
Min 0 |
Item details
| Field |
Type |
Required |
Description |
| item.name |
string |
Yes
|
Max 255 characters |
| item.description |
string |
Yes
|
Max 500 characters |
| item.sellers_item_identification |
string |
No
|
|
| item.type |
string |
No
|
PRODUCT or SERVICE |
Price details
| Field |
Type |
Required |
Description |
| price.price_amount |
number |
Yes
|
Greater than 0. Up to 8 decimal places, so a price below 0.01 is allowed |
| price.base_quantity |
number |
Yes
|
Min 0.01 |
| price.price_unit |
string |
Yes
|
Max 3 characters — must exist in Invoice Quantity Codes (e.g. C62) |
Summary
Required top-level objects:
accounting_customer_partylegal_monetary_totalinvoice_line
Fully optional sections:
- Document references
- Payment means
- Allowance / charge
- Tax totals
