Schema Objects | Staple AI

This page documents every object in the Staple Global E-Invoice schema. Each table shows fields, types, requiredness, descriptions, and country-specific notes. Required values marked Optional* are conditionally required by some countries — check the country notes column.

Conventions

These conventions apply across the entire schema unless a specific field overrides them.

Date fields - All fields of type string (date) use the format YYYY-MM-DD.
Time fields - All fields of type string (time) use the format HH:MM:SS in UTC. Milliseconds are not supported.
Amount fields - All fields of type string (decimal) are represented with 2 decimal places, e.g. "1500.00".
Percent fields - All percent fields use string (decimal), e.g. "7.0" for 7%.
Country codes - Use ISO 3166-1 alpha-2 codes.
Currency codes - Use ISO 4217 codes.

Quick links: Invoice · Address · Advance · Attachment · Card · Charge · CreditTransfer · DeliveryDetails · DirectDebit · Discount · DocumentRef · DueDate · ExchangeRate · Identity · Inbox · Item · Line · LineCharge · LineDiscount · Name · Note · Online · Ordering · Party · PayInstructions · PaymentDetails · PayTerms · Period · Person · Registration · Stamp · Tax · TaxCombo · TaxIdentity · Totals

Invoice

Root object — top-level invoice document.

Field	Type	Required	Description	Country Notes
`Country`	`string`	Required	Alpha-2 country code identifying the tax regime.	—
`ComplianceStandards`	`string[]`	Optional	Addon keys that activate country-specific validation rules. e.g. `["eu-en16931-v2017","de-xrechnung-v3"]`	🇩🇪 Required for DE. 🇮🇹 Required for IT. 🇫🇷 Required for FR. 🇲🇽 Required for MX. 🇵🇱 Required for PL.
`TypeFlags`	`string[]`	Optional	Scenario tags: `simplified`, `reverse-charge`, `self-billed`, `partial`, `prepayment`	🇪🇺 Use `reverse-charge` for EU cross-border B2B transactions.
`UUID`	`string (uuid)`	Optional	Universally unique identifier for the invoice.	—
`Type`	`string`	Optional	Invoice type. Defaults to `standard`. Allowed values: `standard`, `credit-note`, `debit-note`, `corrective`, `proforma`.	—
`DocGroup`	`string`	Optional	Invoice series / group identifier. Groups invoices by project, date range, or type. Prepended to `DocNumber` with a dash when output format has no series field.	—
`DocNumber`	`string`	Required	Sequential invoice number. Max 50 characters. e.g. `"INV-0042"`	—
`IssueDate`	`string (date)`	Required	Invoice issue date in `YYYY-MM-DD` format.	—
`IssueTime`	`string (time)`	Optional	Invoice issue time in `HH:MM:SS` format.	🇲🇽 🇲🇾 Required for MX and MY.
`OpDate`	`string (date)`	Optional	Date when the invoiced operation became effective.	—
`ValueDate`	`string (date)`	Optional	Date taxes become accountable. Defaults to `IssueDate`.	—
`Currency`	`string`	Required	ISO 4217 currency code. e.g. `"EUR"`, `"MYR"`, `"MXN"`	—
`ExchangeRates`	`ExchangeRate[]`	Optional	Exchange rates for converting foreign currency amounts.	🇲🇾 Required when invoice currency is not MYR.
`Preceding`	`DocumentRef[]`	Optional	References to prior invoices this document replaces or extends.	Required when `Type` is `credit-note`, `corrective`, or `debit-note`.
`Tax`	`Tax`	Optional	Invoice-level tax configuration. See Tax object for details.	—
`Supplier`	`Party`	Required	The entity issuing the invoice and responsible for tax obligations.	—
`Customer`	`Party`	Optional	The entity receiving the goods or services. May be omitted for simplified invoices.	🇲🇾 🇩🇪 🇮🇹 Required for MY B2B, DE, IT.
`Lines`	`Line[]`	Optional	Invoice line items. Recommended for all invoices.	—
`Discounts`	`Discount[]`	Optional	Invoice-level discounts applied to the whole document.	—
`Charges`	`Charge[]`	Optional	Invoice-level surcharges applied to the whole document.	—
`Ordering`	`Ordering`	Optional	Ordering details including purchase order references and buyer/seller parties.	🇩🇪 Buyer reference in `Ordering.Code` required for DE XRechnung.
`Payment`	`PaymentDetails`	Optional	Payment terms, instructions, and advance payments.	—
`Delivery`	`DeliveryDetails`	Optional	Delivery address, date, and receiver details.	🇲🇾 Used for shipping recipient details in MY.
`Notes`	`Note[]`	Optional	Free-text annotations, legal details, or correction reasons.	🇪🇸 VeriFactu requires a `general` key note.
`Complements`	`string[]`	Optional	Structured country-specific complement values.	🇲🇽 Used for CFDI payment complements in MX.
`Attachments`	`Attachment[]`	Optional	Supporting documents. Not for alternative PDF versions.	—
`Meta`	`string`	Optional	Semi-structured data that does not fit the main body.	—
`Totals`	`Totals`	Calculated	Summary of all invoice totals including taxes. Computed server-side — do not submit.	—

Type values

Value	Description
`standard`	A regular commercial invoice document between a supplier and customer.
`credit-note`	Reflects a refund, either partial or complete, of the preceding document. A credit note effectively extends the previous document.
`debit-note`	An additional set of charges to be added to the preceding document.
`corrective`	Corrected invoice that completely replaces the preceding document.
`proforma`	For a client’s validation before sending a final invoice.

Party

Used for Supplier, Customer, and embedded party references in Ordering and Delivery.

Field	Type	Required	Description	Country Notes
`Name`	`string`	Optional*	Legal name of the organization or individual.	🇲🇾 Required, max 300 chars.
`Alias`	`string`	Optional	Alternate short name.	—
`TaxID`	`TaxIdentity`	Optional*	Tax registration identity. Determines the invoice tax regime when `Invoice.Country` is omitted.	🇲🇾 🇩🇪 🇲🇽 🇮🇹 Required for most countries.
`Identities`	`Identity[]`	Optional	Additional registration codes: BRN, SST, NRIC, MSIC, Peppol ID, GLN, etc.	🇲🇾 Required: BRN or NRIC, SST number, MSIC code.
`People`	`Person[]`	Optional	Physical contact persons representing the party.	—
`Inboxes`	`Inbox[]`	Optional	Electronic document delivery inboxes. e.g. Peppol participant ID.	🇩🇪 Peppol inbox required for DE Peppol delivery.
`Addresses`	`Address[]`	Optional*	Postal addresses.	🇲🇾 🇩🇪 🇮🇹 Required for MY, DE, IT.
`Emails`	`object[]`	Optional	Email addresses. Each object has a single `Addr` string field.	—
`Telephones`	`object[]`	Optional	Phone numbers. Each object has a single `Num` string field.	🇲🇾 Optional but recommended for MY.
`Registration`	`Registration`	Optional	Company registration details such as capital, office, and book entries.	🇮🇹 Required for IT (company registration).
`Ext`	`string`	Optional	Regime-specific extension codes for the party.	—
`Meta`	`string`	Optional	Additional semi-structured data.	🇲🇾 Use for MSIC business activity description: key `msic-description`.

TaxIdentity

Tax registration details for a party.

Field	Type	Required	Description	Country Notes
`Country`	`string`	Required	Alpha-2 country code where the tax ID was issued.	—
`Code`	`string`	Optional*	The tax identification number. Format varies by country: VAT number, TIN, RFC, GST ID, etc.	🇲🇾 TIN (max 14 chars). 🇲🇽 RFC format. 🇩🇪 USt-IdNr format.
`Scheme`	`string`	Optional	Override the default tax scheme. e.g. `"VAT"`, `"GST"`	—

Address

Postal or fiscal address.

Field	Type	Required	Description	Country Notes
`Num`	`string`	Optional	House or building number.	—
`Street`	`string`	Optional*	First line of the street address.	—
`StreetExtra`	`string`	Optional	Additional street address line.	—
`Locality`	`string`	Optional*	City, town, or district name.	—
`Region`	`string`	Optional	Province, county, or state name.	—
`State`	`string`	Optional	State or province code where required.	🇲🇽 Required for MX.
`Code`	`string`	Optional*	Post or ZIP code.	—
`Country`	`string`	Optional*	ISO alpha-2 country code.	—
`PoBox`	`string`	Optional	Post office box number.	—

Identity

Additional registration or classification code for a party or item.

Field	Type	Required	Description	Country Notes
`Code`	`string`	Required	The actual identity value. e.g. `"202001234567"`	—
`Key`	`string`	Optional	Classification key. Common values: `BRN`, `NRIC`, `PASSPORT`, `SST`, `MSIC`, `TTX`, `TIN`. Mutually exclusive with `Type`.	🇲🇾 Use `BRN`, `SST`, `MSIC` keys for MY.
`Type`	`string`	Optional	Context-specific type code. Mutually exclusive with `Key`.	—
`Label`	`string`	Optional	Human-readable label. e.g. `"GLN"`, `"DUNS"`	—
`Scope`	`string`	Optional	Context: `tax` or `legal`.	—
`Country`	`string`	Optional	Country that issued this identity (alpha-2).	—

Inbox

Electronic document delivery inbox, e.g. Peppol participant ID.

Field	Type	Required	Description	Country Notes
`Scheme`	`string`	Optional	Scheme ID (ISO 6523 or CEF code). e.g. `"0088"` for GLN, `"0192"` for Peppol.	—
`Code`	`string`	Optional	Inbox identifier code. Mutually exclusive with `URL` and `Email`.	—
`URL`	`string`	Optional	Inbox URL. Mutually exclusive with `Code` and `Email`.	—
`Email`	`string`	Optional	Inbox email address. Mutually exclusive with `Code` and `URL`.	—
`Key`	`string`	Optional	Type of inbox for disambiguation between multiple inboxes.	—

Person

A physical contact person representing a party.

Field	Type	Required	Description	Country Notes
`Name`	`Name`	Required	Structured name of the person.	—
`Label`	`string`	Optional	Role label. e.g. `"Attn"`, `"Contact"`	—
`Role`	`string`	Optional	Job title or role description.	—
`Emails`	`object[]`	Optional	Email addresses belonging to the person.	—
`Telephones`	`object[]`	Optional	Phone numbers belonging to the person.	—

Name

Structured personal name.

Field	Type	Required	Description	Country Notes
`Given`	`string`	Optional	First or given name.	—
`Surname`	`string`	Optional	Family name.	—
`Surname2`	`string`	Optional	Second family name, common in Spanish-speaking countries.	—
`Prefix`	`string`	Optional	Name prefix. e.g. `"Mr."`, `"Dr."`	—
`Alias`	`string`	Optional	Preferred name or nickname.	—

Registration

Company registration details required by some countries.

Field	Type	Required	Description	Country Notes
`Capital`	`string (decimal)`	Optional	Share capital amount.	🇮🇹 Required for IT.
`Currency`	`string`	Optional	Currency of the capital (ISO 4217).	—
`Office`	`string`	Optional	Registration office name.	—
`Entry`	`string`	Optional	Registry entry number.	—

Line

A single row in the invoice.

Field	Type	Required	Description	Country Notes
`Quantity`	`string (decimal)`	Required	Number of units. e.g. `"10.00"`	—
`Item`	`Item`	Required	Product or service details.	—
`Taxes`	`TaxCombo[]`	Optional*	Tax categories applicable to this line.	Required for all countries with tax obligations.
`Discounts`	`LineDiscount[]`	Optional	Discounts applied to this line.	—
`Charges`	`LineCharge[]`	Optional	Charges applied to this line.	—
`Period`	`Period`	Optional	Service delivery period for this line.	—
`Notes`	`Note[]`	Optional	Line-specific annotations.	—
`Ext`	`string`	Optional	Regime-specific extension codes for the line.	—
`Total`	`string (decimal)`	Calculated	Line total after discounts. Computed server-side.	—

Item

Product or service being sold.

Field	Type	Required	Description	Country Notes
`Name`	`string`	Required	Brief product or service name.	🇲🇾 Max 300 chars.
`Description`	`string`	Optional	Long description of the product or service.	—
`Price`	`string (decimal)`	Required	Unit price. Zero or positive. e.g. `"250.00"`	—
`Currency`	`string`	Optional	Item currency if different from invoice currency.	—
`Unit`	`string`	Optional	Unit of measure. e.g. `"piece"`, `"hour"`, `"kg"`, `"KGM"`	🇲🇾 Uses UN/ECE Rec 20 codes.
`Key`	`string`	Optional	Item classification: `goods` or `services`.	—
`Ref`	`string`	Optional	Supplier’s internal product reference code.	—
`Identities`	`Identity[]`	Optional*	Product codes: HS tariff code, classification code, SKU, UNSPSC, etc.	🇲🇾 Classification code (`CLASS` key) required. Tariff code (`PTC` key) for goods.
`Origin`	`string`	Optional	Country of origin (alpha-2). e.g. `"GB"`	🇲🇾 Optional for MY goods.
`Ext`	`string`	Optional*	Regime-specific extension codes for the item.	🇲🇽 Required: `mx-cfdi-prod-serv`. 🇮🇹 Required: `it-sdi-nature`. 🇧🇷 Required: `br-nfse-service-code`.

TaxCombo

Tax category and rate applicable to a line item.

Field	Type	Required	Description	Country Notes
`Cat`	`string`	Required	Tax category code. e.g. `"VAT"`, `"GST"`, `"SST"`, `"IGST"`	—
`Rate`	`string`	Optional	Named rate. e.g. `"standard"`, `"reduced"`, `"zero"`, `"exempt"`	—
`Percent`	`string (decimal)`	Optional	Override percentage. e.g. `"7.0"`. Calculated from `Rate` if omitted.	—
`Ext`	`string`	Optional*	Regime-specific tax extension codes.	🇲🇽 Required: `mx-cfdi-tax-type`. 🇮🇹 Required: `it-sdi-nature`. 🇧🇷 Required: `br-nfe-fiscal-operation`. 🇪🇸 Required: `es-verifactu-regime`.

LineDiscount

Discount applied to a single line item.

Field	Type	Required	Description	Country Notes
`Amount`	`string (decimal)`	Required	Fixed discount amount. Calculated from `Percent` if provided.	—
`Percent`	`string (decimal)`	Optional	Percentage to apply. e.g. `"10.0"`	—
`Reason`	`string`	Optional	Description of why the discount was applied.	—
`Key`	`string`	Optional	Discount type key. e.g. `standard`, `special-agreement`, `sample`	—

LineCharge

Surcharge applied to a single line item.

Field	Type	Required	Description	Country Notes
`Amount`	`string (decimal)`	Required	Fixed charge amount. Calculated from `Percent` if provided.	—
`Percent`	`string (decimal)`	Optional	Percentage to apply. e.g. `"5.0"`	—
`Reason`	`string`	Optional	Description of why the charge was applied.	—
`Key`	`string`	Optional	Charge type key. e.g. `delivery`, `packing`, `handling`, `insurance`	—

Discount

Invoice-level discount applied to the whole document.

Field	Type	Required	Description	Country Notes
`Amount`	`string (decimal)`	Required	Fixed discount amount. Calculated from `Percent` if provided.	—
`Percent`	`string (decimal)`	Optional	Percentage of invoice sum to deduct. e.g. `"10.0"`	—
`Reason`	`string`	Optional	Description of the discount.	🇲🇾 Reason description required for MY.
`Taxes`	`TaxCombo[]`	Optional	Taxes applicable to the discount.	—

Charge

Invoice-level surcharge applied to the whole document.

Field	Type	Required	Description	Country Notes
`Amount`	`string (decimal)`	Required	Fixed charge amount. Calculated from `Percent` if provided.	—
`Percent`	`string (decimal)`	Optional	Percentage of invoice sum to add. e.g. `"5.0"`	—
`Reason`	`string`	Optional	Description of the charge.	🇲🇾 Reason description required for MY.
`Key`	`string`	Optional	Charge type: `stamp-duty`, `customs`, `delivery`, `packing`, `handling`, `insurance`, `storage`, `admin`	—
`Taxes`	`TaxCombo[]`	Optional	Taxes applicable to the charge.	—

Ordering

Purchase order references and related document links.

Field	Type	Required	Description	Country Notes
`Code`	`string`	Optional	Buyer’s purchase order number for internal routing.	🇩🇪 Required for DE XRechnung (buyer reference BT-10).
`Period`	`Period`	Optional	Billing period the document covers.	—
`Buyer`	`Party`	Optional	Party responsible for payment if different from Customer.	—
`Seller`	`Party`	Optional	Tax-liable seller if different from Supplier. Used for marketplace scenarios.	—
`Issuer`	`Party`	Optional	Third party responsible for issuing the document (e.g. fiscal representative).	—
`Purchases`	`DocumentRef[]`	Optional	Buyer’s purchase order document references.	—
`Contracts`	`DocumentRef[]`	Optional	Contract document references.	—
`Projects`	`DocumentRef[]`	Optional	Project document references.	—

PaymentDetails

Payment terms, instructions, and pre-payments.

Field	Type	Required	Description	Country Notes
`Payee`	`Party`	Optional	Party to receive payment, if different from Supplier.	—
`Terms`	`PayTerms`	Optional	Payment terms and due dates.	—
`Advances`	`Advance[]`	Optional	Pre-payments to deduct from the amount due.	🇲🇾 Use for MY prepayment fields.
`Instructions`	`PayInstructions`	Optional	How and where to send payment.	—

PayTerms

Payment conditions and due dates.

Field	Type	Required	Description	Country Notes
`Key`	`string`	Optional	Type of terms: `end-of-month`, `due-date`, `deferred`, `instant`, `elective`, `pending`, `advanced`, `delivery`	—
`DueDates`	`DueDate[]`	Optional	Specific payment due dates with amounts.	—
`Notes`	`string`	Optional	Free-text payment conditions. Max 256 characters. e.g. `"Payment is Cash"`	🇲🇾 Used for MY payment terms text.

DueDate

A specific payment date with an associated amount.

Field	Type	Required	Description	Country Notes
`Date`	`string (date)`	Required	When the payment is due.	—
`Amount`	`string (decimal)`	Required	Amount due by this date.	—
`Percent`	`string (decimal)`	Optional	Percentage of total due by this date. e.g. `"50.0"`. Use at most one percent entry per document.	—
`Notes`	`string`	Optional	Additional notes for this due date. Max 256 characters.	—

PayInstructions

How payment should be made.

Field	Type	Required	Description	Country Notes
`Key`	`string`	Required	Payment method: `any`, `card`, `credit-transfer`, `credit-transfer+sepa`, `debit-transfer`, `cash`, `cheque`, `bank-draft`, `direct-debit`, `direct-debit+sepa`, `online`, `promissory-note`, `netting`, `other`	🇲🇾 Maps to MY payment mode code.
`Ref`	`string`	Optional	Remittance reference linking payment to invoice.	—
`Detail`	`string`	Optional	Free-text description of the payment method.	—
`CreditTransfer`	`CreditTransfer[]`	Optional	Bank transfer details.	🇲🇾 Supplier bank account number stored here.
`Card`	`Card`	Optional	Card payment reference details.	—
`DirectDebit`	`DirectDebit`	Optional	Direct debit mandate details.	—
`Online`	`Online[]`	Optional	Online payment links.	—
`Notes`	`string`	Optional	Additional payment instructions. Max 256 characters.	—

CreditTransfer

Bank transfer payment details.

Field	Type	Required	Description	Country Notes
`IBAN`	`string`	Optional	International Bank Account Number.	—
`BIC`	`string`	Optional	Bank Identifier Code (SWIFT).	—
`Number`	`string`	Optional	Account number when IBAN is not available.	🇲🇾 MY bank account number goes here.
`Name`	`string`	Optional	Bank name.	—

Card

Payment card reference.

Field	Type	Required	Description	Country Notes
`Last4`	`string`	Optional	Last 4 digits of the card PAN.	—
`First6`	`string`	Optional	First 6 digits of the card PAN.	—
`Holder`	`string`	Optional	Card holder name.	—

DirectDebit

Direct debit mandate details.

Field	Type	Required	Description	Country Notes
`Ref`	`string`	Optional	Mandate reference assigned by payee.	—
`Creditor`	`string`	Optional	Bank-assigned creditor ID.	—
`Account`	`string`	Optional	Account to be debited.	—

Online

Online payment link.

Field	Type	Required	Description	Country Notes
`URL`	`string (uri)`	Required	Payment URL.	—
`Key`	`string`	Optional	Identifier for this payment method. e.g. `"paypal"`	—
`Label`	`string`	Optional	Display name for the payment provider.	—

Advance

A pre-payment made before the invoice was issued.

Field	Type	Required	Description	Country Notes
`Description`	`string`	Required	Details about the advance payment. Max 256 characters.	—
`Amount`	`string (decimal)`	Required	Amount paid in advance.	🇲🇾 Maps to MY PrePayment Amount.
`Date`	`string (date)`	Optional	Date the advance was made.	🇲🇾 Maps to MY PrePayment Date.
`Ref`	`string`	Optional	Reference ID for the advance payment.	🇲🇾 Maps to MY PrePayment Reference Number.
`Key`	`string`	Optional	Payment method used for the advance. Same values as PayInstructions.Key.	—
`Grant`	`boolean`	Optional	Set `true` if the advance came from a public grant or subsidy.	—
`Currency`	`string`	Optional	Currency of the advance if different from the invoice currency.	—

DeliveryDetails

Goods delivery destination and recipient.

Field	Type	Required	Description	Country Notes
`Receiver`	`Party`	Optional	Party receiving the goods. Not responsible for taxes.	🇲🇾 Maps to MY Shipping Recipient (Name, TIN, BRN, Address).
`Date`	`string (date)`	Optional	Expected delivery date.	—
`Period`	`Period`	Optional	Delivery window if a specific date is not available.	—
`Identities`	`Identity[]`	Optional	Codes to identify the delivery. e.g. customs form numbers.	🇲🇾 Use for MY Customs Form No.1/No.2 reference numbers.

DocumentRef

Reference to an existing document — used in Preceding and Ordering.

Field	Type	Required	Description	Country Notes
`Code`	`string`	Required	The document number or identifier being referenced.	—
`IssueDate`	`string (date)`	Optional	Issue date of the referenced document.	—
`Series`	`string`	Optional	Series of the referenced document.	—
`Reason`	`string`	Optional	Why this document is being referenced.	—
`Period`	`Period`	Optional	Tax period the referenced document applied to.	—
`Stamps`	`Stamp[]`	Optional	Official seals of approval from tax authorities or intermediaries.	🇲🇽 Used for CFDI cancellation stamps.
`Ext`	`string`	Optional	Regime-specific correction method codes.	—

ExchangeRate

Currency conversion rate.

Field	Type	Required	Description	Country Notes
`From`	`string`	Required	Source currency code (ISO 4217).	—
`To`	`string`	Required	Target currency code (ISO 4217).	🇲🇾 Target must be `MYR` for MY.
`Amount`	`string (decimal)`	Required	How much 1 unit of `From` is worth in `To`.	—
`At`	`string (datetime)`	Optional	Effective date and time of the rate.	—

Note

Free-text annotation or legal detail.

Field	Type	Required	Description	Country Notes
`Text`	`string`	Required	The note content. Max 256 characters.	—
`Key`	`string`	Optional	Subject classification: `general`, `legal`, `payment`, `goods`, `customs`, `reason`, `tax`, `regulatory`, `other`	🇪🇸 VeriFactu requires `Key: "general"` note with invoice description.
`Code`	`string`	Optional	Additional code to identify the note.	—

Attachment

Supporting document attached to the invoice.

Field	Type	Required	Description	Country Notes
`URL`	`string (uri)`	Required	Where to find the attachment.	—
`Name`	`string`	Optional	Filename of the attachment.	—
`Description`	`string`	Optional	Why this attachment is included.	—
`MIME`	`string`	Optional	MIME type. e.g. `"application/pdf"`, `"application/xml"`	—
`Code`	`string`	Optional	Code identifying the payload type.	—

Stamp

Official seal from a tax authority or intermediary.

Field	Type	Required	Description	Country Notes
`Prv`	`string`	Required	Provider key identifying the stamping agency. e.g. `"sat-mx"`, `"sdi-it"`	—
`Val`	`string`	Required	The stamp value issued by the agency.	—

Period

A date range used for billing, delivery, or tax periods. Both Start and End dates are inclusive.

Field	Type	Required	Description	Country Notes
`Start`	`string (date)`	Required	Start date of the period (inclusive).	—
`End`	`string (date)`	Required	End date of the period (inclusive).	—

Tax

Tax defines a summary of the taxes that may be applied to an invoice.

Field	Type	Required	Description
`PricesInclude`	`string`	Optional	Category of the tax already included in the line item prices. Useful for price-inclusive invoices.
`Rounding`	`string`	Optional	Rounding model used to perform tax calculations. Allowed values: `precise`, `currency`.
`Point`	`string`	Optional	Event that triggers tax liability. Allowed values: `issue`, `delivery`, `payment`.
`Ext`	`string`	Optional	Additional extensions applied to the invoice as a whole.
`Notes`	`Note[]`	Optional	Tax-related notes, typically used for exemption reasons or category-specific explanations.
`Meta`	`string`	Optional	Additional processing data that should not be relied upon by recipients.

Tax rounding values

Value	Description
`precise`	Default model. Maintains maximum precision during calculations.
`currency`	Rounds to currency precision before summation. Easier to reconcile visually but can introduce rounding differences.

Tax point values

Value	Description
`issue`	Tax point is the invoice issue date.
`delivery`	Tax point is the actual delivery date.
`payment`	Tax point is the date on which payment is made.

Totals

Totals contains the summaries of all calculations for the invoice. This object is calculated server-side — do not submit it as part of the request payload.

Field	Type	Description
`Sum`	`string (decimal)`	Total of all line item amounts.
`Discount`	`string (decimal)`	Total of all discounts applied at the document level.
`Charge`	`string (decimal)`	Total of all charges applied at the document level.
`TaxIncluded`	`string (decimal)`	Total tax amount already included in prices.
`Total`	`string (decimal)`	Net total amount after discounts and charges, excluding tax.
`Tax`	`string (decimal)`	Total indirect tax amount applied to the invoice.
`TotalWithTax`	`string (decimal)`	Final total amount after applying indirect taxes.
`RetainedTax`	`string (decimal)`	Total tax amount retained or withheld by the customer.
`Rounding`	`string (decimal)`	Adjustment amount applied to satisfy rounding rules.
`Payable`	`string (decimal)`	Final amount to be paid after retained taxes and rounding.
`Advance`	`string (decimal)`	Total amount already paid in advance by the customer.
`Due`	`string (decimal)`	Remaining amount that needs to be paid.

Alpha-2 Country Codes

The Country field and other country code fields in the schema use ISO 3166-1 alpha-2 codes. The table below lists the supported tax regimes.

View supported alpha-2 country codes

Code	Country
`AE`	United Arab Emirates
`AR`	Argentina
`AT`	Austria
`BE`	Belgium
`BR`	Brazil
`CA`	Canada
`CH`	Switzerland
`CO`	Colombia
`DE`	Germany
`DK`	Denmark
`EL`	Greece
`ES`	Spain
`FR`	France
`GB`	United Kingdom
`IE`	Ireland
`IN`	India
`IT`	Italy
`MX`	Mexico
`NL`	The Netherlands
`PL`	Poland
`PT`	Portugal
`SE`	Sweden
`SG`	Singapore
`US`	United States of America

Currency Codes

The Currency field and other currency code fields in the schema use ISO 4217 alpha-3 codes.

View supported currency codes

Code	Currency	Country
`AED`	UAE Dirham	United Arab Emirates
`ARS`	Argentine Peso	Argentina
`AUD`	Australian Dollar	Australia
`BRL`	Brazilian Real	Brazil
`CAD`	Canadian Dollar	Canada
`CHF`	Swiss Franc	Switzerland
`CNY`	Chinese Yuan Renminbi	China
`COP`	Colombian Peso	Colombia
`DKK`	Danish Krone	Denmark
`EUR`	Euro	Austria, Belgium, France, Germany, Greece, Ireland, Italy, The Netherlands, Portugal, Spain
`GBP`	Pound Sterling	United Kingdom
`HKD`	Hong Kong Dollar	Hong Kong
`INR`	Indian Rupee	India
`JPY`	Japanese Yen	Japan
`KRW`	South Korean Won	South Korea
`MXN`	Mexican Peso	Mexico
`MYR`	Malaysian Ringgit	Malaysia
`NZD`	New Zealand Dollar	New Zealand
`PLN`	Polish Zloty	Poland
`SEK`	Swedish Krona	Sweden
`SGD`	Singapore Dollar	Singapore
`THB`	Thai Baht	Thailand
`USD`	US Dollar	United States of America
`VND`	Vietnamese Dong	Vietnam