> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.staple.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.staple.ai/_mcp/server.
# Schema Objects
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](#invoice) · [Address](#address) · [Advance](#advance) · [Attachment](#attachment) · [Card](#card) · [Charge](#charge) · [CreditTransfer](#credittransfer) · [DeliveryDetails](#deliverydetails) · [DirectDebit](#directdebit) · [Discount](#discount) · [DocumentRef](#documentref) · [DueDate](#duedate) · [ExchangeRate](#exchangerate) · [Identity](#identity) · [Inbox](#inbox) · [Item](#item) · [Line](#line) · [LineCharge](#linecharge) · [LineDiscount](#linediscount) · [Name](#name) · [Note](#note) · [Online](#online) · [Ordering](#ordering) · [Party](#party) · [PayInstructions](#payinstructions) · [PaymentDetails](#paymentdetails) · [PayTerms](#payterms) · [Period](#period) · [Person](#person) · [Registration](#registration) · [Stamp](#stamp) · [Tax](#tax) · [TaxCombo](#taxcombo) · [TaxIdentity](#taxidentity) · [Totals](#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[]`](#exchangerate) | Optional | Exchange rates for converting foreign currency amounts. | 🇲🇾 Required when invoice currency is not MYR. |
| `Preceding` | [`DocumentRef[]`](#documentref) | Optional | References to prior invoices this document replaces or extends. | Required when `Type` is `credit-note`, `corrective`, or `debit-note`. |
| `Tax` | [`Tax`](#tax) | Optional | Invoice-level tax configuration. See [Tax](#tax) object for details. | — |
| `Supplier` | [`Party`](#party) | Required | The entity issuing the invoice and responsible for tax obligations. | — |
| `Customer` | [`Party`](#party) | Optional | The entity receiving the goods or services. May be omitted for simplified invoices. | 🇲🇾 🇩🇪 🇮🇹 Required for MY B2B, DE, IT. |
| `Lines` | [`Line[]`](#line) | Optional | Invoice line items. Recommended for all invoices. | — |
| `Discounts` | [`Discount[]`](#discount) | Optional | Invoice-level discounts applied to the whole document. | — |
| `Charges` | [`Charge[]`](#charge) | Optional | Invoice-level surcharges applied to the whole document. | — |
| `Ordering` | [`Ordering`](#ordering) | Optional | Ordering details including purchase order references and buyer/seller parties. | 🇩🇪 Buyer reference in `Ordering.Code` required for DE XRechnung. |
| `Payment` | [`PaymentDetails`](#paymentdetails) | Optional | Payment terms, instructions, and advance payments. | — |
| `Delivery` | [`DeliveryDetails`](#deliverydetails) | Optional | Delivery address, date, and receiver details. | 🇲🇾 Used for shipping recipient details in MY. |
| `Notes` | [`Note[]`](#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[]`](#attachment) | Optional | Supporting documents. Not for alternative PDF versions. | — |
| `Meta` | `string` | Optional | Semi-structured data that does not fit the main body. | — |
| `Totals` | [`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`](#taxidentity) | Optional\* | Tax registration identity. Determines the invoice tax regime when `Invoice.Country` is omitted. | 🇲🇾 🇩🇪 🇲🇽 🇮🇹 Required for most countries. |
| `Identities` | [`Identity[]`](#identity) | Optional | Additional registration codes: BRN, SST, NRIC, MSIC, Peppol ID, GLN, etc. | 🇲🇾 Required: BRN or NRIC, SST number, MSIC code. |
| `People` | [`Person[]`](#person) | Optional | Physical contact persons representing the party. | — |
| `Inboxes` | [`Inbox[]`](#inbox) | Optional | Electronic document delivery inboxes. e.g. Peppol participant ID. | 🇩🇪 Peppol inbox required for DE Peppol delivery. |
| `Addresses` | [`Address[]`](#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`](#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`](#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`](#item) | Required | Product or service details. | — |
| `Taxes` | [`TaxCombo[]`](#taxcombo) | Optional\* | Tax categories applicable to this line. | Required for all countries with tax obligations. |
| `Discounts` | [`LineDiscount[]`](#linediscount) | Optional | Discounts applied to this line. | — |
| `Charges` | [`LineCharge[]`](#linecharge) | Optional | Charges applied to this line. | — |
| `Period` | [`Period`](#period) | Optional | Service delivery period for this line. | — |
| `Notes` | [`Note[]`](#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[]`](#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[]`](#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[]`](#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`](#period) | Optional | Billing period the document covers. | — |
| `Buyer` | [`Party`](#party) | Optional | Party responsible for payment if different from Customer. | — |
| `Seller` | [`Party`](#party) | Optional | Tax-liable seller if different from Supplier. Used for marketplace scenarios. | — |
| `Issuer` | [`Party`](#party) | Optional | Third party responsible for issuing the document (e.g. fiscal representative). | — |
| `Purchases` | [`DocumentRef[]`](#documentref) | Optional | Buyer's purchase order document references. | — |
| `Contracts` | [`DocumentRef[]`](#documentref) | Optional | Contract document references. | — |
| `Projects` | [`DocumentRef[]`](#documentref) | Optional | Project document references. | — |
## PaymentDetails
Payment terms, instructions, and pre-payments.
| Field | Type | Required | Description | Country Notes |
| -------------- | ------------------------------------- | -------- | ----------------------------------------------------- | ---------------------------------- |
| `Payee` | [`Party`](#party) | Optional | Party to receive payment, if different from Supplier. | — |
| `Terms` | [`PayTerms`](#payterms) | Optional | Payment terms and due dates. | — |
| `Advances` | [`Advance[]`](#advance) | Optional | Pre-payments to deduct from the amount due. | 🇲🇾 Use for MY prepayment fields. |
| `Instructions` | [`PayInstructions`](#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[]`](#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[]`](#credittransfer) | Optional | Bank transfer details. | 🇲🇾 Supplier bank account number stored here. |
| `Card` | [`Card`](#card) | Optional | Card payment reference details. | — |
| `DirectDebit` | [`DirectDebit`](#directdebit) | Optional | Direct debit mandate details. | — |
| `Online` | [`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](#payinstructions). | — |
| `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`](#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`](#period) | Optional | Delivery window if a specific date is not available. | — |
| `Identities` | [`Identity[]`](#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`](#period) | Optional | Tax period the referenced document applied to. | — |
| `Stamps` | [`Stamp[]`](#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[]`](#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 |