Models
Transmitted Document Summary
Properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The Recommand document ID. Use it with the other document endpoints. Example: "doc_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
teamId | string | Yes | The ID of the team the document belongs to. Example: "team_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
companyId | string | Yes | The ID of the company the document was sent for or received by. Example: "c_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
direction | incoming | outgoing | Yes | Whether the document was received by this company (incoming) or sent by it (outgoing). Example: "incoming". Values: incoming, outgoing |
senderId | string | Yes | The Peppol address of the sender, as scheme:identifier. Example: "0208:1012081766" |
receiverId | string | null | Yes | The Peppol address of the receiver, as scheme:identifier. Null for documents that were never addressed on the network, such as email-only sends and French e-reporting reports. Example: "0208:0428643097" |
docTypeId | string | Yes | The full Peppol document type identifier the document was exchanged under. It names the syntax and the customization the document follows. Example: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1" |
processId | string | Yes | The Peppol process identifier the document was exchanged under. It names the business process the document type is used in. Example: "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" |
countryC1 | string | Yes | The country of the originating sender (Peppol corner 1), in ISO 3166-1 alpha-2 format. Peppol requires it on every transmission so receivers can apply country-specific rules. Example: "BE" |
type | string (enum) | Yes | What kind of document this is. unknown means the document could not be recognised as one of the supported types, in which case parsed is null and only the XML is available. Example: "invoice". Values: invoice, creditNote, selfBillingInvoice, selfBillingCreditNote, messageLevelResponse, frenchInvoicingCdar, frenchB2CSalesReport, frenchB2CPaymentReport, frenchB2BiInvoiceReport, frenchB2BiPaymentReport, unknown |
readAt | string | null | Yes | When the document was marked as read. Null while it is unread, which is what puts an incoming document in the inbox |
createdAt | string | Yes | When the document was sent or received |
updatedAt | string | Yes | When the document record last changed |
parsed | Invoice | Credit Note | Self Billing Invoice |
validation | Document Validation | null | Yes |
sentOverPeppol | boolean | Yes | Whether the document was handed over to the Peppol network. False for a document that was only delivered by email. Whether it reached the recipient is what deliveryStatus and deliveries say. Example: true |
sentOverEmail | boolean | Yes | Whether the document was delivered by email, either as the only channel or alongside Peppol. Example: false |
emailRecipients | string[] | Yes | The email addresses the document was delivered to. Empty when it was not sent by email. Example: [] |
labels | object[] | Yes | The labels assigned to this document. Manage them with the assign and unassign label endpoints |
peppolMessageId | string | null | Yes | The AS4 message ID of the transmission. Null when the document did not travel over Peppol, and for playground teams, whose transmissions are simulated |
peppolConversationId | string | null | Yes | The AS4 conversation ID the transmission belongs to. It ties a document to the responses that follow it |
receivedPeppolSignalMessage | string | null | Yes | The AS4 signal message the receiving access point returned to acknowledge an outgoing transmission. Null for incoming documents and when the access point returned none |
envelopeId | string | null | Yes | The envelope ID of the document, also known as the SBDH instance identifier (Standard Business Document Header Instance Identifier) |
reporting | French Reporting Status | null | Yes |
deliveryStatus | pending | delivered | failed | null | Yes | Whether the document reached its recipient, summarised over its deliveries: delivered when at least one delivery was confirmed, failed when every delivery failed, pending while any is still awaiting the channel's confirmation. Null for documents without deliveries, such as incoming documents and filed reports. Example: "delivered". Values: pending, delivered, failed, null |
deliveries | object[] | Yes | Where an outgoing document stands with each recipient: one entry per channel and address it was sent to. Empty for incoming documents and filed reports. sentOverPeppol says the document was handed to the network; a delivery says whether it arrived |
parsed (Any of)
Invoice:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceNumber | string | Yes | The number the seller assigned to the invoice. Example: "INV-2024-001" |
issueDate | string (date) | Yes | The date the invoice was issued, as YYYY-MM-DD. Example: "2024-03-20". Format: date |
dueDate | string | null | No | The date the payment is due, as YYYY-MM-DD. Example: "2024-04-20". Format: date |
note | string | null | No | A free text note about the invoice as a whole. Example: "Thank you for your business" |
buyerReference | string | null | No | A reference the buyer asked you to put on the invoice so they can route it internally (BT-10). If neither this nor purchaseOrderReference is provided, the invoice number is used. For a German public authority addressed by its Leitweg-ID (recipient scheme 0204), this must be that Leitweg-ID: it is filled in when left out, and a different value is refused. Example: "PO-2024-001" |
purchaseOrderReference | string | null | No | A reference to a related purchase order. Example: "PO-2024-001" |
salesOrderReference | string | null | No | A reference to a related sales order. Example: "SO-2024-001" |
despatchReference | string | null | No | A reference to a related despatch advice document (e.g. packing slip). Example: "DE-2024-001" |
seller | object | Yes | |
buyer | object | Yes | |
delivery | Delivery | null | No |
paymentMeans | object[] | null | No | Optional payment information. For most invoices, this should be provided. For prepaid invoices, this could be omitted |
paymentTerms | object | null | No | Optional payment terms |
lines | object[] | Yes | The invoice lines. At least one line is required. Min items: 1 |
discounts | object[] | null | No | Optional global discounts |
surcharges | object[] | null | No | Optional global surcharges |
totals | Totals | null | No |
vat | Provided VAT totals | null | No |
attachments | object[] | null | No | Optional attachments to the invoice |
currency | string (enum) | No | The currency of the invoice. Defaults to EUR. Default: EUR. Example: "EUR". Values: XUA, AFN, DZD, ARS, AMD, AWG, AUD, AZN, BSD, BHD, THB, PAB, BBD, BYN, BZD, BMD, VES, VED, BOB, XBA, XBB, XBD, XBC, BRL, BND, BGN, BIF, CVE, CAD, KYD, XOF, XAF, XPF, CLP, XTS, COP, KMF, CDF, BAM, NIO, CRC, CUP, CZK, GMD, DKK, MKD, DJF, STN, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, XAU, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, KWD, AOA, MMK, LAK, GEL, LBP, ALL, HNL, LRD, LYD, SZL, LSL, MGA, MWK, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, MRU, TOP, PKR, XPD, MOP, UYU, PHP, XPT, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, XDR, RSD, SCR, SLE, XAG, SGD, PEN, SBD, KGS, SOS, TJS, SSP, LKR, XSU, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, XXX, TTD, MNT, TND, TRY, TMT, AED, UGX, CLF, COU, UYW, UYI, USD, USN, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWG, PLN |
countrySpecific | Country Specific Billing | null | No |
parsed.seller properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.buyer properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.delivery (One of)
Delivery:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | No | The date of the delivery. Example: "2025-03-20". Format: date |
locationIdentifier | object | null | No | The identifier of the delivery location. Schemes can be found here. Example: {"scheme":"0088","identifier":"123456789"} |
location | object | No | |
recipientName | string | No | The name of the party to which the goods and services are delivered. Example: "Company Ltd." |
parsed.delivery.locationIdentifier properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
parsed.delivery.location properties
| Name | Type | Required | Description |
|---|---|---|---|
street | string | null | No | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | null | No | Example: "Brussels" |
postalZone | string | null | No | Example: "1000" |
country | string | Yes | Example: "BE" |
parsed.paymentMeans properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | No | The name of the payment means. Example: "Credit Transfer" |
paymentMethod | cash | credit_transfer | debit_transfer | bank_card | credit_card | debit_card | sepa_credit_transfer | sepa_direct_debit | other | No | How the invoice is to be paid. Defaults to credit_transfer. Accepted values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other. Default: credit_transfer. Example: "credit_transfer". Values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other |
reference | string | No | The payment reference the buyer should quote when paying, such as a structured communication. Default: ``. Example: "INV-2026-001" |
iban | string | null | No | The account the payment is to be made to, usually an IBAN. A credit transfer needs one. Leave it out when there is no account to pay into, as with a direct debit or a card payment. Example: "BE1234567890" |
financialInstitutionBranch | string | null | No | An identifier for the payment service provider where a payment account is located. Such as a BIC or a national clearing code where required |
parsed.paymentTerms properties
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | The payment terms as free text. Example: "Net 30" |
parsed.lines properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | null | No | A line number. If not provided, it will be calculated automatically. Example: "1" |
name | string | No | The name of the item or service being billed. Default: ``. Example: "Consulting Services" |
description | string | null | No | A longer description of the item or service. Example: "Professional consulting services" |
note | string | null | No | A textual note that gives unstructured information that is relevant to this line |
buyersId | string | null | No | The item identifier of the item as defined by the buyer. Example: "CS-001" |
sellersId | string | null | No | The item identifier of the item as defined by the seller. This is typically a product code or SKU. Example: "CS-001" |
standardId | object | null | No | The standard identifier of the item based on a registered scheme. Schemes can be found here |
documentReference | string | null | No | A reference to a related document, mostly used to refer to a related invoice. Example: "INV-2024-001" |
orderLineReference | string | null | No | A reference to a related order line |
commodityClassifications | object[] | null | No | Optional commodity classifications |
additionalItemProperties | object[] | null | No | Optional additional item properties |
originCountry | string | null | No | The country of origin of the item. Example: "BE" |
quantity | string | No | The number of units billed on this line, expressed in unitCode. Default: 1.00. Example: "21.00" |
unitCode | string | No | Recommended unit codes can be found here. Default: C62. Example: "HUR" |
netPriceAmount | string | Yes | The price of one unit excluding VAT, after any discount that is already reflected in the price. Example: "12.40" |
baseQuantity | string | null | No | The number of units to which the price refers. When greater than 1, the price is for a batch/pack of this size. The actual unit price is netPriceAmount / baseQuantity. Example: "1" |
discounts | object[] | null | No | Optional discounts for the line |
surcharges | object[] | null | No | Optional surcharges for the line |
netAmount | string | null | No | The total net amount of the line: quantity * netPriceAmount. Rounded to 2 decimal places. If not provided, it will be calculated automatically. Example: "21.00" |
vat | object | Yes |
parsed.lines.standardId properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0160" |
identifier | string | Yes | Example: "10986700" |
parsed.lines.commodityClassifications properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string (enum) | Yes | The scheme of the item classification code. Can be found here. Example: "SN". Values: AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CC, CG, CL, CR, CV, DR, DW, EC, EF, EMD, EN, FS, GB, GMN, GN, GS, HS, IB, IN, IS, IT, IZ, MA, MF, MN, MP, NB, ON, PD, PL, PO, PV, QS, RC, RN, RU, RY, SA, SG, SK, SN, SRS, SRT, SRU, SRV, SRW, SRX, SRY, SRZ, SS, SSA, SSB, SSC, SSD, SSE, SSF, SSG, SSH, SSI, SSJ, SSK, SSL, SSM, SSN, SSO, SSP, SSQ, SSR, SSS, SST, SSU, SSV, SSW, SSX, SSY, SSZ, ST, STA, STB, STC, STD, STE, STF, STG, STH, STI, STJ, STK, STL, STM, STN, STO, STP, STQ, STR, STS, STT, STU, STV, STW, STX, STY, STZ, SUA, SUB, SUC, SUD, SUE, SUF, SUG, SUH, SUI, SUJ, SUK, SUL, SUM, TG, TSN, TSO, TSP, TSQ, TSR, TSS, TST, TSU, UA, UP, VN, VP, VS, VX, ZZZ, PPI |
schemeVersion | string | null | No | |
value | string | Yes | The value of the item classification code. Example: "123456" |
parsed.lines.additionalItemProperties properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Example: "Color" |
value | string | Yes | Example: "Red" |
parsed.lines.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.discounts.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.surcharges.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.totals (One of)
Totals:
If not provided, the totals will be calculated from the document lines.
| Name | Type | Required | Description |
|---|---|---|---|
linesAmount | string | null | No | The tax exclusive total amount of all lines. Rounded to 2 decimal places. Example: "21.00" |
discountAmount | string | null | No | The tax exclusive total amount of all discounts. If not provided, this will be calculated automatically. Example: "21.00" |
surchargeAmount | string | null | No | The tax exclusive total amount of all surcharges. If not provided, this will be calculated automatically. Example: "21.00" |
taxExclusiveAmount | string | Yes | The tax exclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
taxInclusiveAmount | string | Yes | The tax inclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
payableAmount | string | null | No | The amount to be paid. If not provided, this will be taxInclusiveAmount. Can be used in combination with paidAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
paidAmount | string | null | No | The amount paid. If not provided, this will be taxInclusiveAmount - payableAmount. Can be used in combination with payableAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
parsed.vat (One of)
Provided VAT totals:
| Name | Type | Required | Description |
|---|---|---|---|
totalVatAmount | string | Yes | The total VAT amount of the document, the sum of the VAT amounts of all subtotals. Example: "21.00" |
subtotals | object[] | Yes | One entry for every combination of VAT category and rate used in the document |
parsed.vat.subtotals properties
| Name | Type | Required | Description |
|---|---|---|---|
taxableAmount | string | Yes | The total amount in this VAT category and rate that the VAT is calculated on. Example: "21.00" |
vatAmount | string | Yes | The VAT amount for this VAT category and rate. Example: "21.00" |
category | AE | E | S | Z | G | O | K | L | M | B | Yes | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
exemptionReasonCode | string | null | No | If the invoice is exempt from VAT, this (or exemptionReason) is required. The exemption reason code identifier must belong to the CEF VATEX code list found here |
exemptionReason | string | null | No | If the invoice is exempt from VAT, this (or exemptionReasonCode) is required. The exemption reason must be a textual statement of the reason why the amount is exempt from VAT or why no VAT is charged |
parsed.attachments properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | An identifier for the attachment within the document. Example: "ATT-001" |
mimeCode | string | No | MIME type of the document (e.g. application/pdf, text/csv, image/png). Default: application/pdf. Example: "application/pdf" |
filename | string | Yes | Filename for an embedded attachment. This is included in the Peppol XML only when embeddedDocument is provided. For URL-only attachments, the document contains an external reference and the filename is not embedded. Example: "contract.pdf" |
description | string | null | No | A short description of what the attachment contains. Example: "Signed contract" |
embeddedDocument | string | null | No | The contents of the attachment, base64 encoded. Provide this or url |
url | string | null | No | A link to the attachment, for when the contents are not embedded. Provide this or embeddedDocument. Example: "https://example.com/contract.pdf" |
parsed.countrySpecific (One of)
Credit Note:
| Name | Type | Required | Description |
|---|---|---|---|
creditNoteNumber | string | Yes | Example: "CN-2024-001" |
issueDate | string (date) | Yes | Example: "2024-03-20". Format: date |
dueDate | string | null | No | The date the credited amount is due (BT-9). Optional: when left out, the credit note states no due date. In CII, including Factur-X, it is the payment due date of the payment terms; in UBL it is stated on the first payment means, so a UBL credit note without paymentMeans does not carry it. Example: "2024-04-20". Format: date |
note | string | null | No | Example: "Thank you for your business" |
buyerReference | string | null | No | A reference the buyer asked you to put on the credit note so they can route it internally (BT-10). If neither this nor purchaseOrderReference is provided, the credit note number is used. For a German public authority addressed by its Leitweg-ID (recipient scheme 0204), this must be that Leitweg-ID: it is filled in when left out, and a different value is refused. Example: "PO-2024-001" |
invoiceReferences | object[] | No | References to one or more invoices that are being credited. A French regulated credit note (countrySpecific.country FR) needs at least one reference with its issueDate. Default: `` |
purchaseOrderReference | string | null | No | A reference to a related purchase order. Example: "PO-2024-001" |
salesOrderReference | string | null | No | A reference to a related sales order. Example: "SO-2024-001" |
despatchReference | string | null | No | A reference to a related despatch advice document (e.g. packing slip). Example: "DE-2024-001" |
seller | object | Yes | |
buyer | object | Yes | |
delivery | Delivery | null | No |
paymentMeans | object[] | null | No | |
paymentTerms | object | null | No | |
lines | object[] | Yes | Min items: 1 |
discounts | object[] | null | No | Optional global discounts |
surcharges | object[] | null | No | Optional global surcharges |
totals | Totals | null | No |
vat | Provided VAT totals | null | No |
attachments | object[] | null | No | Optional attachments to the credit note |
currency | string (enum) | No | The currency of the credit note. Defaults to EUR. Default: EUR. Example: "EUR". Values: XUA, AFN, DZD, ARS, AMD, AWG, AUD, AZN, BSD, BHD, THB, PAB, BBD, BYN, BZD, BMD, VES, VED, BOB, XBA, XBB, XBD, XBC, BRL, BND, BGN, BIF, CVE, CAD, KYD, XOF, XAF, XPF, CLP, XTS, COP, KMF, CDF, BAM, NIO, CRC, CUP, CZK, GMD, DKK, MKD, DJF, STN, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, XAU, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, KWD, AOA, MMK, LAK, GEL, LBP, ALL, HNL, LRD, LYD, SZL, LSL, MGA, MWK, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, MRU, TOP, PKR, XPD, MOP, UYU, PHP, XPT, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, XDR, RSD, SCR, SLE, XAG, SGD, PEN, SBD, KGS, SOS, TJS, SSP, LKR, XSU, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, XXX, TTD, MNT, TND, TRY, TMT, AED, UGX, CLF, COU, UYW, UYI, USD, USN, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWG, PLN |
countrySpecific | Country Specific Billing | null | No |
parsed.invoiceReferences properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The reference to the invoice that is being credited. Example: "INV-2024-001" |
issueDate | string | null | No | The issue date of the invoice that is being credited. Example: "2024-03-20". Format: date |
parsed.seller properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.buyer properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.delivery (One of)
Delivery:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | No | The date of the delivery. Example: "2025-03-20". Format: date |
locationIdentifier | object | null | No | The identifier of the delivery location. Schemes can be found here. Example: {"scheme":"0088","identifier":"123456789"} |
location | object | No | |
recipientName | string | No | The name of the party to which the goods and services are delivered. Example: "Company Ltd." |
parsed.delivery.locationIdentifier properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
parsed.delivery.location properties
| Name | Type | Required | Description |
|---|---|---|---|
street | string | null | No | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | null | No | Example: "Brussels" |
postalZone | string | null | No | Example: "1000" |
country | string | Yes | Example: "BE" |
parsed.paymentMeans properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | No | The name of the payment means. Example: "Credit Transfer" |
paymentMethod | cash | credit_transfer | debit_transfer | bank_card | credit_card | debit_card | sepa_credit_transfer | sepa_direct_debit | other | No | How the invoice is to be paid. Defaults to credit_transfer. Accepted values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other. Default: credit_transfer. Example: "credit_transfer". Values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other |
reference | string | No | The payment reference the buyer should quote when paying, such as a structured communication. Default: ``. Example: "INV-2026-001" |
iban | string | null | No | The account the payment is to be made to, usually an IBAN. A credit transfer needs one. Leave it out when there is no account to pay into, as with a direct debit or a card payment. Example: "BE1234567890" |
financialInstitutionBranch | string | null | No | An identifier for the payment service provider where a payment account is located. Such as a BIC or a national clearing code where required |
parsed.paymentTerms properties
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | Example: "Net 30" |
parsed.lines properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | null | No | A line number. If not provided, it will be calculated automatically. Example: "1" |
name | string | No | The name of the item or service being billed. Default: ``. Example: "Consulting Services" |
description | string | null | No | A longer description of the item or service. Example: "Professional consulting services" |
note | string | null | No | A textual note that gives unstructured information that is relevant to this line |
buyersId | string | null | No | The item identifier of the item as defined by the buyer. Example: "CS-001" |
sellersId | string | null | No | The item identifier of the item as defined by the seller. This is typically a product code or SKU. Example: "CS-001" |
standardId | object | null | No | The standard identifier of the item based on a registered scheme. Schemes can be found here |
documentReference | string | null | No | A reference to a related document, mostly used to refer to a related invoice. Example: "INV-2024-001" |
orderLineReference | string | null | No | A reference to a related order line |
commodityClassifications | object[] | null | No | Optional commodity classifications |
additionalItemProperties | object[] | null | No | Optional additional item properties |
originCountry | string | null | No | The country of origin of the item. Example: "BE" |
quantity | string | No | The number of units billed on this line, expressed in unitCode. Default: 1.00. Example: "21.00" |
unitCode | string | No | Recommended unit codes can be found here. Default: C62. Example: "HUR" |
netPriceAmount | string | Yes | The price of one unit excluding VAT, after any discount that is already reflected in the price. Example: "12.40" |
baseQuantity | string | null | No | The number of units to which the price refers. When greater than 1, the price is for a batch/pack of this size. The actual unit price is netPriceAmount / baseQuantity. Example: "1" |
discounts | object[] | null | No | Optional discounts for the line |
surcharges | object[] | null | No | Optional surcharges for the line |
netAmount | string | null | No | The total net amount of the line: quantity * netPriceAmount. Rounded to 2 decimal places. If not provided, it will be calculated automatically. Example: "21.00" |
vat | object | Yes |
parsed.lines.standardId properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0160" |
identifier | string | Yes | Example: "10986700" |
parsed.lines.commodityClassifications properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string (enum) | Yes | The scheme of the item classification code. Can be found here. Example: "SN". Values: AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CC, CG, CL, CR, CV, DR, DW, EC, EF, EMD, EN, FS, GB, GMN, GN, GS, HS, IB, IN, IS, IT, IZ, MA, MF, MN, MP, NB, ON, PD, PL, PO, PV, QS, RC, RN, RU, RY, SA, SG, SK, SN, SRS, SRT, SRU, SRV, SRW, SRX, SRY, SRZ, SS, SSA, SSB, SSC, SSD, SSE, SSF, SSG, SSH, SSI, SSJ, SSK, SSL, SSM, SSN, SSO, SSP, SSQ, SSR, SSS, SST, SSU, SSV, SSW, SSX, SSY, SSZ, ST, STA, STB, STC, STD, STE, STF, STG, STH, STI, STJ, STK, STL, STM, STN, STO, STP, STQ, STR, STS, STT, STU, STV, STW, STX, STY, STZ, SUA, SUB, SUC, SUD, SUE, SUF, SUG, SUH, SUI, SUJ, SUK, SUL, SUM, TG, TSN, TSO, TSP, TSQ, TSR, TSS, TST, TSU, UA, UP, VN, VP, VS, VX, ZZZ, PPI |
schemeVersion | string | null | No | |
value | string | Yes | The value of the item classification code. Example: "123456" |
parsed.lines.additionalItemProperties properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Example: "Color" |
value | string | Yes | Example: "Red" |
parsed.lines.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.discounts.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.surcharges.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.totals (One of)
Totals:
If not provided, the totals will be calculated from the document lines.
| Name | Type | Required | Description |
|---|---|---|---|
linesAmount | string | null | No | The tax exclusive total amount of all lines. Rounded to 2 decimal places. Example: "21.00" |
discountAmount | string | null | No | The tax exclusive total amount of all discounts. If not provided, this will be calculated automatically. Example: "21.00" |
surchargeAmount | string | null | No | The tax exclusive total amount of all surcharges. If not provided, this will be calculated automatically. Example: "21.00" |
taxExclusiveAmount | string | Yes | The tax exclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
taxInclusiveAmount | string | Yes | The tax inclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
payableAmount | string | null | No | The amount to be paid. If not provided, this will be taxInclusiveAmount. Can be used in combination with paidAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
paidAmount | string | null | No | The amount paid. If not provided, this will be taxInclusiveAmount - payableAmount. Can be used in combination with payableAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
parsed.vat (One of)
Provided VAT totals:
| Name | Type | Required | Description |
|---|---|---|---|
totalVatAmount | string | Yes | The total VAT amount of the document, the sum of the VAT amounts of all subtotals. Example: "21.00" |
subtotals | object[] | Yes | One entry for every combination of VAT category and rate used in the document |
parsed.vat.subtotals properties
| Name | Type | Required | Description |
|---|---|---|---|
taxableAmount | string | Yes | The total amount in this VAT category and rate that the VAT is calculated on. Example: "21.00" |
vatAmount | string | Yes | The VAT amount for this VAT category and rate. Example: "21.00" |
category | AE | E | S | Z | G | O | K | L | M | B | Yes | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
exemptionReasonCode | string | null | No | If the invoice is exempt from VAT, this (or exemptionReason) is required. The exemption reason code identifier must belong to the CEF VATEX code list found here |
exemptionReason | string | null | No | If the invoice is exempt from VAT, this (or exemptionReasonCode) is required. The exemption reason must be a textual statement of the reason why the amount is exempt from VAT or why no VAT is charged |
parsed.attachments properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | An identifier for the attachment within the document. Example: "ATT-001" |
mimeCode | string | No | MIME type of the document (e.g. application/pdf, text/csv, image/png). Default: application/pdf. Example: "application/pdf" |
filename | string | Yes | Filename for an embedded attachment. This is included in the Peppol XML only when embeddedDocument is provided. For URL-only attachments, the document contains an external reference and the filename is not embedded. Example: "contract.pdf" |
description | string | null | No | A short description of what the attachment contains. Example: "Signed contract" |
embeddedDocument | string | null | No | The contents of the attachment, base64 encoded. Provide this or url |
url | string | null | No | A link to the attachment, for when the contents are not embedded. Provide this or embeddedDocument. Example: "https://example.com/contract.pdf" |
parsed.countrySpecific (One of)
Self Billing Invoice:
Self billing invoice
| Name | Type | Required | Description |
|---|---|---|---|
invoiceNumber | string | Yes | The number the seller assigned to the invoice. Example: "INV-2024-001" |
issueDate | string (date) | Yes | The date the invoice was issued, as YYYY-MM-DD. Example: "2024-03-20". Format: date |
dueDate | string | null | No | The date the payment is due, as YYYY-MM-DD. Example: "2024-04-20". Format: date |
note | string | null | No | A free text note about the invoice as a whole. Example: "Thank you for your business" |
buyerReference | string | null | No | A reference the buyer asked you to put on the invoice so they can route it internally (BT-10). If neither this nor purchaseOrderReference is provided, the invoice number is used. For a German public authority addressed by its Leitweg-ID (recipient scheme 0204), this must be that Leitweg-ID: it is filled in when left out, and a different value is refused. Example: "PO-2024-001" |
purchaseOrderReference | string | null | No | A reference to a related purchase order. Example: "PO-2024-001" |
salesOrderReference | string | null | No | A reference to a related sales order. Example: "SO-2024-001" |
despatchReference | string | null | No | A reference to a related despatch advice document (e.g. packing slip). Example: "DE-2024-001" |
seller | object | Yes | |
buyer | object | Yes | |
delivery | Delivery | null | No |
paymentMeans | object[] | null | No | Optional payment information. For most invoices, this should be provided. For prepaid invoices, this could be omitted |
paymentTerms | object | null | No | Optional payment terms |
lines | object[] | Yes | The invoice lines. At least one line is required. Min items: 1 |
discounts | object[] | null | No | Optional global discounts |
surcharges | object[] | null | No | Optional global surcharges |
totals | Totals | null | No |
vat | Provided VAT totals | null | No |
attachments | object[] | null | No | Optional attachments to the invoice |
currency | string (enum) | Yes | The currency of the invoice. Defaults to EUR. Default: EUR. Example: "EUR". Values: XUA, AFN, DZD, ARS, AMD, AWG, AUD, AZN, BSD, BHD, THB, PAB, BBD, BYN, BZD, BMD, VES, VED, BOB, XBA, XBB, XBD, XBC, BRL, BND, BGN, BIF, CVE, CAD, KYD, XOF, XAF, XPF, CLP, XTS, COP, KMF, CDF, BAM, NIO, CRC, CUP, CZK, GMD, DKK, MKD, DJF, STN, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, XAU, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, KWD, AOA, MMK, LAK, GEL, LBP, ALL, HNL, LRD, LYD, SZL, LSL, MGA, MWK, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, MRU, TOP, PKR, XPD, MOP, UYU, PHP, XPT, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, XDR, RSD, SCR, SLE, XAG, SGD, PEN, SBD, KGS, SOS, TJS, SSP, LKR, XSU, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, XXX, TTD, MNT, TND, TRY, TMT, AED, UGX, CLF, COU, UYW, UYI, USD, USN, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWG, PLN |
countrySpecific | Country Specific Billing | null | No |
parsed.seller properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.buyer properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.delivery (One of)
Delivery:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | No | The date of the delivery. Example: "2025-03-20". Format: date |
locationIdentifier | object | null | No | The identifier of the delivery location. Schemes can be found here. Example: {"scheme":"0088","identifier":"123456789"} |
location | object | No | |
recipientName | string | No | The name of the party to which the goods and services are delivered. Example: "Company Ltd." |
parsed.delivery.locationIdentifier properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
parsed.delivery.location properties
| Name | Type | Required | Description |
|---|---|---|---|
street | string | null | No | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | null | No | Example: "Brussels" |
postalZone | string | null | No | Example: "1000" |
country | string | Yes | Example: "BE" |
parsed.paymentMeans properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | No | The name of the payment means. Example: "Credit Transfer" |
paymentMethod | cash | credit_transfer | debit_transfer | bank_card | credit_card | debit_card | sepa_credit_transfer | sepa_direct_debit | other | No | How the invoice is to be paid. Defaults to credit_transfer. Accepted values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other. Default: credit_transfer. Example: "credit_transfer". Values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other |
reference | string | No | The payment reference the buyer should quote when paying, such as a structured communication. Default: ``. Example: "INV-2026-001" |
iban | string | null | No | The account the payment is to be made to, usually an IBAN. A credit transfer needs one. Leave it out when there is no account to pay into, as with a direct debit or a card payment. Example: "BE1234567890" |
financialInstitutionBranch | string | null | No | An identifier for the payment service provider where a payment account is located. Such as a BIC or a national clearing code where required |
parsed.paymentTerms properties
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | The payment terms as free text. Example: "Net 30" |
parsed.lines properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | null | No | A line number. If not provided, it will be calculated automatically. Example: "1" |
name | string | No | The name of the item or service being billed. Default: ``. Example: "Consulting Services" |
description | string | null | No | A longer description of the item or service. Example: "Professional consulting services" |
note | string | null | No | A textual note that gives unstructured information that is relevant to this line |
buyersId | string | null | No | The item identifier of the item as defined by the buyer. Example: "CS-001" |
sellersId | string | null | No | The item identifier of the item as defined by the seller. This is typically a product code or SKU. Example: "CS-001" |
standardId | object | null | No | The standard identifier of the item based on a registered scheme. Schemes can be found here |
documentReference | string | null | No | A reference to a related document, mostly used to refer to a related invoice. Example: "INV-2024-001" |
orderLineReference | string | null | No | A reference to a related order line |
commodityClassifications | object[] | null | No | Optional commodity classifications |
additionalItemProperties | object[] | null | No | Optional additional item properties |
originCountry | string | null | No | The country of origin of the item. Example: "BE" |
quantity | string | No | The number of units billed on this line, expressed in unitCode. Default: 1.00. Example: "21.00" |
unitCode | string | No | Recommended unit codes can be found here. Default: C62. Example: "HUR" |
netPriceAmount | string | Yes | The price of one unit excluding VAT, after any discount that is already reflected in the price. Example: "12.40" |
baseQuantity | string | null | No | The number of units to which the price refers. When greater than 1, the price is for a batch/pack of this size. The actual unit price is netPriceAmount / baseQuantity. Example: "1" |
discounts | object[] | null | No | Optional discounts for the line |
surcharges | object[] | null | No | Optional surcharges for the line |
netAmount | string | null | No | The total net amount of the line: quantity * netPriceAmount. Rounded to 2 decimal places. If not provided, it will be calculated automatically. Example: "21.00" |
vat | object | Yes |
parsed.lines.standardId properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0160" |
identifier | string | Yes | Example: "10986700" |
parsed.lines.commodityClassifications properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string (enum) | Yes | The scheme of the item classification code. Can be found here. Example: "SN". Values: AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CC, CG, CL, CR, CV, DR, DW, EC, EF, EMD, EN, FS, GB, GMN, GN, GS, HS, IB, IN, IS, IT, IZ, MA, MF, MN, MP, NB, ON, PD, PL, PO, PV, QS, RC, RN, RU, RY, SA, SG, SK, SN, SRS, SRT, SRU, SRV, SRW, SRX, SRY, SRZ, SS, SSA, SSB, SSC, SSD, SSE, SSF, SSG, SSH, SSI, SSJ, SSK, SSL, SSM, SSN, SSO, SSP, SSQ, SSR, SSS, SST, SSU, SSV, SSW, SSX, SSY, SSZ, ST, STA, STB, STC, STD, STE, STF, STG, STH, STI, STJ, STK, STL, STM, STN, STO, STP, STQ, STR, STS, STT, STU, STV, STW, STX, STY, STZ, SUA, SUB, SUC, SUD, SUE, SUF, SUG, SUH, SUI, SUJ, SUK, SUL, SUM, TG, TSN, TSO, TSP, TSQ, TSR, TSS, TST, TSU, UA, UP, VN, VP, VS, VX, ZZZ, PPI |
schemeVersion | string | null | No | |
value | string | Yes | The value of the item classification code. Example: "123456" |
parsed.lines.additionalItemProperties properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Example: "Color" |
value | string | Yes | Example: "Red" |
parsed.lines.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.discounts.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.surcharges.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.totals (One of)
Totals:
If not provided, the totals will be calculated from the document lines.
| Name | Type | Required | Description |
|---|---|---|---|
linesAmount | string | null | No | The tax exclusive total amount of all lines. Rounded to 2 decimal places. Example: "21.00" |
discountAmount | string | null | No | The tax exclusive total amount of all discounts. If not provided, this will be calculated automatically. Example: "21.00" |
surchargeAmount | string | null | No | The tax exclusive total amount of all surcharges. If not provided, this will be calculated automatically. Example: "21.00" |
taxExclusiveAmount | string | Yes | The tax exclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
taxInclusiveAmount | string | Yes | The tax inclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
payableAmount | string | null | No | The amount to be paid. If not provided, this will be taxInclusiveAmount. Can be used in combination with paidAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
paidAmount | string | null | No | The amount paid. If not provided, this will be taxInclusiveAmount - payableAmount. Can be used in combination with payableAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
parsed.vat (One of)
Provided VAT totals:
| Name | Type | Required | Description |
|---|---|---|---|
totalVatAmount | string | Yes | The total VAT amount of the document, the sum of the VAT amounts of all subtotals. Example: "21.00" |
subtotals | object[] | Yes | One entry for every combination of VAT category and rate used in the document |
parsed.vat.subtotals properties
| Name | Type | Required | Description |
|---|---|---|---|
taxableAmount | string | Yes | The total amount in this VAT category and rate that the VAT is calculated on. Example: "21.00" |
vatAmount | string | Yes | The VAT amount for this VAT category and rate. Example: "21.00" |
category | AE | E | S | Z | G | O | K | L | M | B | Yes | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
exemptionReasonCode | string | null | No | If the invoice is exempt from VAT, this (or exemptionReason) is required. The exemption reason code identifier must belong to the CEF VATEX code list found here |
exemptionReason | string | null | No | If the invoice is exempt from VAT, this (or exemptionReasonCode) is required. The exemption reason must be a textual statement of the reason why the amount is exempt from VAT or why no VAT is charged |
parsed.attachments properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | An identifier for the attachment within the document. Example: "ATT-001" |
mimeCode | string | No | MIME type of the document (e.g. application/pdf, text/csv, image/png). Default: application/pdf. Example: "application/pdf" |
filename | string | Yes | Filename for an embedded attachment. This is included in the Peppol XML only when embeddedDocument is provided. For URL-only attachments, the document contains an external reference and the filename is not embedded. Example: "contract.pdf" |
description | string | null | No | A short description of what the attachment contains. Example: "Signed contract" |
embeddedDocument | string | null | No | The contents of the attachment, base64 encoded. Provide this or url |
url | string | null | No | A link to the attachment, for when the contents are not embedded. Provide this or embeddedDocument. Example: "https://example.com/contract.pdf" |
parsed.countrySpecific (One of)
Self Billing Credit Note:
Self billing credit note
| Name | Type | Required | Description |
|---|---|---|---|
creditNoteNumber | string | Yes | Example: "CN-2024-001" |
issueDate | string (date) | Yes | Example: "2024-03-20". Format: date |
dueDate | string | null | No | The date the credited amount is due (BT-9). Optional: when left out, the credit note states no due date. In CII, including Factur-X, it is the payment due date of the payment terms; in UBL it is stated on the first payment means, so a UBL credit note without paymentMeans does not carry it. Example: "2024-04-20". Format: date |
note | string | null | No | Example: "Thank you for your business" |
buyerReference | string | null | No | A reference the buyer asked you to put on the credit note so they can route it internally (BT-10). If neither this nor purchaseOrderReference is provided, the credit note number is used. For a German public authority addressed by its Leitweg-ID (recipient scheme 0204), this must be that Leitweg-ID: it is filled in when left out, and a different value is refused. Example: "PO-2024-001" |
invoiceReferences | object[] | Yes | References to one or more invoices that are being credited. A French regulated credit note (countrySpecific.country FR) needs at least one reference with its issueDate. Default: `` |
purchaseOrderReference | string | null | No | A reference to a related purchase order. Example: "PO-2024-001" |
salesOrderReference | string | null | No | A reference to a related sales order. Example: "SO-2024-001" |
despatchReference | string | null | No | A reference to a related despatch advice document (e.g. packing slip). Example: "DE-2024-001" |
seller | object | Yes | |
buyer | object | Yes | |
delivery | Delivery | null | No |
paymentMeans | object[] | null | No | |
paymentTerms | object | null | No | |
lines | object[] | Yes | Min items: 1 |
discounts | object[] | null | No | Optional global discounts |
surcharges | object[] | null | No | Optional global surcharges |
totals | Totals | null | No |
vat | Provided VAT totals | null | No |
attachments | object[] | null | No | Optional attachments to the credit note |
currency | string (enum) | Yes | The currency of the credit note. Defaults to EUR. Default: EUR. Example: "EUR". Values: XUA, AFN, DZD, ARS, AMD, AWG, AUD, AZN, BSD, BHD, THB, PAB, BBD, BYN, BZD, BMD, VES, VED, BOB, XBA, XBB, XBD, XBC, BRL, BND, BGN, BIF, CVE, CAD, KYD, XOF, XAF, XPF, CLP, XTS, COP, KMF, CDF, BAM, NIO, CRC, CUP, CZK, GMD, DKK, MKD, DJF, STN, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, XAU, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, KWD, AOA, MMK, LAK, GEL, LBP, ALL, HNL, LRD, LYD, SZL, LSL, MGA, MWK, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, MRU, TOP, PKR, XPD, MOP, UYU, PHP, XPT, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, XDR, RSD, SCR, SLE, XAG, SGD, PEN, SBD, KGS, SOS, TJS, SSP, LKR, XSU, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, XXX, TTD, MNT, TND, TRY, TMT, AED, UGX, CLF, COU, UYW, UYI, USD, USN, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWG, PLN |
countrySpecific | Country Specific Billing | null | No |
parsed.invoiceReferences properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The reference to the invoice that is being credited. Example: "INV-2024-001" |
issueDate | string | null | No | The issue date of the invoice that is being credited. Example: "2024-03-20". Format: date |
parsed.seller properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.buyer properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | string (enum) | No | The scheme that corresponds to the enterprise number. Can be found here. Example: "0208". Values: 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0009, 0010, 0011, 0012, 0013, 0014, 0015, 0016, 0017, 0018, 0019, 0020, 0021, 0022, 0023, 0024, 0025, 0026, 0027, 0028, 0029, 0030, 0031, 0032, 0033, 0034, 0035, 0036, 0037, 0038, 0039, 0040, 0041, 0042, 0043, 0044, 0045, 0046, 0047, 0048, 0049, 0050, 0051, 0052, 0053, 0054, 0055, 0056, 0057, 0058, 0059, 0060, 0061, 0062, 0063, 0064, 0065, 0066, 0067, 0068, 0069, 0070, 0071, 0072, 0073, 0074, 0075, 0076, 0077, 0078, 0079, 0080, 0081, 0082, 0083, 0084, 0085, 0086, 0087, 0088, 0089, 0090, 0091, 0093, 0094, 0095, 0096, 0097, 0098, 0099, 0100, 0101, 0102, 0104, 0105, 0106, 0107, 0108, 0109, 0110, 0111, 0112, 0113, 0114, 0115, 0116, 0117, 0118, 0119, 0120, 0121, 0122, 0123, 0124, 0125, 0126, 0127, 0128, 0129, 0130, 0131, 0132, 0133, 0134, 0135, 0136, 0137, 0138, 0139, 0140, 0141, 0142, 0143, 0144, 0145, 0146, 0147, 0148, 0149, 0150, 0151, 0152, 0153, 0154, 0155, 0156, 0157, 0158, 0159, 0160, 0161, 0162, 0163, 0164, 0165, 0166, 0167, 0168, 0169, 0170, 0171, 0172, 0173, 0174, 0175, 0176, 0177, 0178, 0179, 0180, 0183, 0184, 0185, 0186, 0187, 0188, 0189, 0190, 0191, 0192, 0193, 0194, 0195, 0196, 0197, 0198, 0199, 0200, 0201, 0202, 0203, 0204, 0205, 0206, 0207, 0208, 0209, 0210, 0211, 0212, 0213, 0214, 0215, 0216, 0217, 0218, 0219, 0220, 0221, 0222, 0223, 0224, 0225, 0226, 0227, 0228, 0229, 0230, 0231, 0232, 0233, 0234, 0235, 0236, 0237, 0238, 0239, 0240, null |
enterpriseNumber | string | null | No | The national registration number without a country prefix, paired with enterpriseNumberScheme. Example: "1234567894" |
name | string | Yes | The registered name of the party. Example: "Example Company" |
street | string | Yes | The street name and number of the party's address. Example: "Example Street 1" |
street2 | string | null | No | An extra address line, for example a suite or a building name. Example: "Suite 100" |
city | string | Yes | The city of the party's address. Example: "Brussels" |
postalZone | string | Yes | The postal code of the party's address. Example: "1000" |
country | string | Yes | The country of the party's address, as an ISO 3166-1 alpha-2 code. Example: "BE" |
email | string | null | No | The email address of the party. If not provided, the email address will not be included in the document. Example: "email@example.com" |
phone | string | null | No | The phone number of the party. Must contain at least 3 digits. If not provided, the phone number will not be included in the document. Example: "887 654 321" |
parsed.delivery (One of)
Delivery:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | No | The date of the delivery. Example: "2025-03-20". Format: date |
locationIdentifier | object | null | No | The identifier of the delivery location. Schemes can be found here. Example: {"scheme":"0088","identifier":"123456789"} |
location | object | No | |
recipientName | string | No | The name of the party to which the goods and services are delivered. Example: "Company Ltd." |
parsed.delivery.locationIdentifier properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
parsed.delivery.location properties
| Name | Type | Required | Description |
|---|---|---|---|
street | string | null | No | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | null | No | Example: "Brussels" |
postalZone | string | null | No | Example: "1000" |
country | string | Yes | Example: "BE" |
parsed.paymentMeans properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | No | The name of the payment means. Example: "Credit Transfer" |
paymentMethod | cash | credit_transfer | debit_transfer | bank_card | credit_card | debit_card | sepa_credit_transfer | sepa_direct_debit | other | No | How the invoice is to be paid. Defaults to credit_transfer. Accepted values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other. Default: credit_transfer. Example: "credit_transfer". Values: cash, credit_transfer, debit_transfer, bank_card, credit_card, debit_card, sepa_credit_transfer, sepa_direct_debit, other |
reference | string | No | The payment reference the buyer should quote when paying, such as a structured communication. Default: ``. Example: "INV-2026-001" |
iban | string | null | No | The account the payment is to be made to, usually an IBAN. A credit transfer needs one. Leave it out when there is no account to pay into, as with a direct debit or a card payment. Example: "BE1234567890" |
financialInstitutionBranch | string | null | No | An identifier for the payment service provider where a payment account is located. Such as a BIC or a national clearing code where required |
parsed.paymentTerms properties
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | Example: "Net 30" |
parsed.lines properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | null | No | A line number. If not provided, it will be calculated automatically. Example: "1" |
name | string | No | The name of the item or service being billed. Default: ``. Example: "Consulting Services" |
description | string | null | No | A longer description of the item or service. Example: "Professional consulting services" |
note | string | null | No | A textual note that gives unstructured information that is relevant to this line |
buyersId | string | null | No | The item identifier of the item as defined by the buyer. Example: "CS-001" |
sellersId | string | null | No | The item identifier of the item as defined by the seller. This is typically a product code or SKU. Example: "CS-001" |
standardId | object | null | No | The standard identifier of the item based on a registered scheme. Schemes can be found here |
documentReference | string | null | No | A reference to a related document, mostly used to refer to a related invoice. Example: "INV-2024-001" |
orderLineReference | string | null | No | A reference to a related order line |
commodityClassifications | object[] | null | No | Optional commodity classifications |
additionalItemProperties | object[] | null | No | Optional additional item properties |
originCountry | string | null | No | The country of origin of the item. Example: "BE" |
quantity | string | No | The number of units billed on this line, expressed in unitCode. Default: 1.00. Example: "21.00" |
unitCode | string | No | Recommended unit codes can be found here. Default: C62. Example: "HUR" |
netPriceAmount | string | Yes | The price of one unit excluding VAT, after any discount that is already reflected in the price. Example: "12.40" |
baseQuantity | string | null | No | The number of units to which the price refers. When greater than 1, the price is for a batch/pack of this size. The actual unit price is netPriceAmount / baseQuantity. Example: "1" |
discounts | object[] | null | No | Optional discounts for the line |
surcharges | object[] | null | No | Optional surcharges for the line |
netAmount | string | null | No | The total net amount of the line: quantity * netPriceAmount. Rounded to 2 decimal places. If not provided, it will be calculated automatically. Example: "21.00" |
vat | object | Yes |
parsed.lines.standardId properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0160" |
identifier | string | Yes | Example: "10986700" |
parsed.lines.commodityClassifications properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string (enum) | Yes | The scheme of the item classification code. Can be found here. Example: "SN". Values: AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CC, CG, CL, CR, CV, DR, DW, EC, EF, EMD, EN, FS, GB, GMN, GN, GS, HS, IB, IN, IS, IT, IZ, MA, MF, MN, MP, NB, ON, PD, PL, PO, PV, QS, RC, RN, RU, RY, SA, SG, SK, SN, SRS, SRT, SRU, SRV, SRW, SRX, SRY, SRZ, SS, SSA, SSB, SSC, SSD, SSE, SSF, SSG, SSH, SSI, SSJ, SSK, SSL, SSM, SSN, SSO, SSP, SSQ, SSR, SSS, SST, SSU, SSV, SSW, SSX, SSY, SSZ, ST, STA, STB, STC, STD, STE, STF, STG, STH, STI, STJ, STK, STL, STM, STN, STO, STP, STQ, STR, STS, STT, STU, STV, STW, STX, STY, STZ, SUA, SUB, SUC, SUD, SUE, SUF, SUG, SUH, SUI, SUJ, SUK, SUL, SUM, TG, TSN, TSO, TSP, TSQ, TSR, TSS, TST, TSU, UA, UP, VN, VP, VS, VX, ZZZ, PPI |
schemeVersion | string | null | No | |
value | string | Yes | The value of the item classification code. Example: "123456" |
parsed.lines.additionalItemProperties properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Example: "Color" |
value | string | Yes | Example: "Red" |
parsed.lines.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
parsed.lines.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.discounts properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the discount. This must be one of the codes in the UNCL5189 subset code list. For example, 95 for regular discounts. Either reason or reasonCode must be provided. Example: "95" |
reason | string | null | No | The reason for the discount. This is a free text field. Either reason or reasonCode must be provided. Example: "Discount" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.discounts.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.surcharges properties
| Name | Type | Required | Description |
|---|---|---|---|
reasonCode | string | null | No | The reason code for the surcharge. This must be one of the codes in the UNCL7161 subset code list. For example, FC for freight services. Either reason or reasonCode must be provided. Example: "FC" |
reason | string | null | No | The reason for the surcharge. This is a free text field. Either reason or reasonCode must be provided. Example: "Freight services" |
amount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vat | object | Yes |
parsed.surcharges.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | AE | E | S | Z | G | O | K | L | M | B | No | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Default: S. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
parsed.totals (One of)
Totals:
If not provided, the totals will be calculated from the document lines.
| Name | Type | Required | Description |
|---|---|---|---|
linesAmount | string | null | No | The tax exclusive total amount of all lines. Rounded to 2 decimal places. Example: "21.00" |
discountAmount | string | null | No | The tax exclusive total amount of all discounts. If not provided, this will be calculated automatically. Example: "21.00" |
surchargeAmount | string | null | No | The tax exclusive total amount of all surcharges. If not provided, this will be calculated automatically. Example: "21.00" |
taxExclusiveAmount | string | Yes | The tax exclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
taxInclusiveAmount | string | Yes | The tax inclusive total amount of all lines, discounts and surcharges. Rounded to 2 decimal places. Example: "21.00" |
payableAmount | string | null | No | The amount to be paid. If not provided, this will be taxInclusiveAmount. Can be used in combination with paidAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
paidAmount | string | null | No | The amount paid. If not provided, this will be taxInclusiveAmount - payableAmount. Can be used in combination with payableAmount to indicate partial payment or payment rounding. Rounded to 2 decimal places. Example: "21.00" |
parsed.vat (One of)
Provided VAT totals:
| Name | Type | Required | Description |
|---|---|---|---|
totalVatAmount | string | Yes | The total VAT amount of the document, the sum of the VAT amounts of all subtotals. Example: "21.00" |
subtotals | object[] | Yes | One entry for every combination of VAT category and rate used in the document |
parsed.vat.subtotals properties
| Name | Type | Required | Description |
|---|---|---|---|
taxableAmount | string | Yes | The total amount in this VAT category and rate that the VAT is calculated on. Example: "21.00" |
vatAmount | string | Yes | The VAT amount for this VAT category and rate. Example: "21.00" |
category | AE | E | S | Z | G | O | K | L | M | B | Yes | VAT category code. All codes can be found here. When sending regular invoices, you should most often use the S category. When sending an invoice to another EU country, use the AE category for VAT Reverse Charge. In those cases, it is still recommended to include a note in the invoice explaining that the VAT Reverse Charge applies. Example: "S". Values: AE, E, S, Z, G, O, K, L, M, B |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
exemptionReasonCode | string | null | No | If the invoice is exempt from VAT, this (or exemptionReason) is required. The exemption reason code identifier must belong to the CEF VATEX code list found here |
exemptionReason | string | null | No | If the invoice is exempt from VAT, this (or exemptionReasonCode) is required. The exemption reason must be a textual statement of the reason why the amount is exempt from VAT or why no VAT is charged |
parsed.attachments properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | An identifier for the attachment within the document. Example: "ATT-001" |
mimeCode | string | No | MIME type of the document (e.g. application/pdf, text/csv, image/png). Default: application/pdf. Example: "application/pdf" |
filename | string | Yes | Filename for an embedded attachment. This is included in the Peppol XML only when embeddedDocument is provided. For URL-only attachments, the document contains an external reference and the filename is not embedded. Example: "contract.pdf" |
description | string | null | No | A short description of what the attachment contains. Example: "Signed contract" |
embeddedDocument | string | null | No | The contents of the attachment, base64 encoded. Provide this or url |
url | string | null | No | A link to the attachment, for when the contents are not embedded. Provide this or embeddedDocument. Example: "https://example.com/contract.pdf" |
parsed.countrySpecific (One of)
Message Level Response:
Message Level Response received from a recipient
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
issueDate | string (date) | Yes | Example: "2024-03-20". Format: date |
responseCode | AB | AP | RE | Yes | The response code of the message level response (AB: Message acknowledgement, AP: Accepted, RE: Rejected). Example: "AB". Values: AB, AP, RE |
envelopeId | string | Yes | Identifies the document on which the message level response is based |
French Invoicing CDAR:
French invoice lifecycle status using UN/CEFACT Cross Domain Acknowledgement and Response
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
issueDate | string (date-time) | string (date) | Yes |
businessProcess | REGULATED | NON_REGULATED | B2C | B2CINT | B2BINT | OUTOFSCOPE | Yes | Flow classification. | Value | Meaning | | --- | --- | | REGULATED | Regulated French domestic e-invoicing | | NON_REGULATED | Outside the regulated French e-invoicing perimeter | | B2C | B2C sales e-reporting | | B2CINT | International B2C sales e-reporting | | B2BINT | International B2B sales e-reporting | | OUTOFSCOPE | Outside the French e-invoicing and e-reporting reform |. Example: "REGULATED". Values: REGULATED, NON_REGULATED, B2C, B2CINT, B2BINT, OUTOFSCOPE |
phase | 23 | 305 | Yes | CDAR phase. | Value | Meaning | | --- | --- | | 23 | Processing phase | | 305 | Transmission phase |. Example: "23". Values: 23, 305 |
senderRole | string (enum) | Yes | Role of the CDAR sender. CDAR party role code (UNCL 3035). | Value | Meaning | | --- | --- | | BY | Buyer | | AB | Buyer's agent or representative | | DL | Factor | | SE | Seller | | SR | Seller's agent | | WK | Platform or dematerialisation operator | | DFH | French public invoicing portal (PPF) | | PE | Payee | | PR | Payer | | II | Invoicer (invoice issuer) | | IV | Invoicee (party invoiced) |. Example: "WK". Values: BY, AB, DL, SE, SR, WK, DFH, PE, PR, II, IV |
issuerRole | string (enum) | Yes | Role of the party that creates and issues the invoice lifecycle status. This is independent from the CDAR sender role. CDAR party role code (UNCL 3035). | Value | Meaning | | --- | --- | | BY | Buyer | | AB | Buyer's agent or representative | | DL | Factor | | SE | Seller | | SR | Seller's agent | | WK | Platform or dematerialisation operator | | DFH | French public invoicing portal (PPF) | | PE | Payee | | PR | Payer | | II | Invoicer (invoice issuer) | | IV | Invoicee (party invoiced) |. Example: "BY". Values: BY, AB, DL, SE, SR, WK, DFH, PE, PR, II, IV |
issuerLegalId | string | No | Legal identifier of the party setting the status. Required when phase is 23; must be omitted when phase is 305 unless recipientRole is DFH. Example: "200000008" |
issuerLegalIdScheme | string | No | ISO 6523 ICD scheme of the party-setting-status legal identifier. Required together with issuerLegalId. Example: "0002" |
recipientRole | string (enum) | Yes | Role of the CDAR recipient. CDAR party role code (UNCL 3035). | Value | Meaning | | --- | --- | | BY | Buyer | | AB | Buyer's agent or representative | | DL | Factor | | SE | Seller | | SR | Seller's agent | | WK | Platform or dematerialisation operator | | DFH | French public invoicing portal (PPF) | | PE | Payee | | PR | Payer | | II | Invoicer (invoice issuer) | | IV | Invoicee (party invoiced) |. Example: "SE". Values: BY, AB, DL, SE, SR, WK, DFH, PE, PR, II, IV |
recipientLegalId | string | No | Legal identifier of the CDAR recipient. Example: "200000008" |
recipientLegalIdScheme | string | No | ISO 6523 ICD scheme of the CDAR recipient legal identifier. Required together with recipientLegalId. Example: "0002" |
recipientElectronicAddress | string | No | Electronic address of the CDAR recipient. Required when recipientRole is not WK or DFH. Example: "100000009" |
recipientElectronicAddressScheme | string | No | Electronic Address Scheme (EAS) code of the CDAR recipient electronic address. Required together with recipientElectronicAddress. Example: "0225" |
statusCode | string (enum) | Yes | French invoice lifecycle status. | Value | Meaning | | --- | --- | | 200 | Submitted | | 201 | Issued | | 202 | Received | | 203 | Made available | | 204 | Taken in charge (processing started) | | 205 | Approved | | 206 | Partially approved | | 207 | In dispute | | 208 | Suspended | | 209 | Completed | | 210 | Refused | | 211 | Payment sent | | 212 | Collected (cashed) | | 213 | Rejected | | 214 | Validated or pre-validated ("Visée") | | 501 | Inadmissible file |. Example: "200". Values: 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 501 |
statusDate | string (date-time) | string (date) | Yes |
invoiceId | string | Yes | Number of the invoice this status relates to. For status 501, this is the filename of the inadmissible file |
invoiceTypeCode | string (enum) | No | Type of the referenced invoice. Type of the referenced invoice (UNTDID 1001, restricted to the values allowed by BR-FR-04). | Value | Meaning | | --- | --- | | 380 | Commercial invoice | | 389 | Self-billed invoice | | 393 | Factored invoice | | 501 | Self-billed factored invoice | | 386 | Advance payment invoice | | 500 | Self-billed advance payment invoice | | 384 | Corrective invoice | | 471 | Self-billed corrective invoice | | 472 | Factored corrective invoice | | 473 | Self-billed factored corrective invoice | | 261 | Self-billed credit note | | 262 | Global rebate credit note | | 381 | Credit note | | 396 | Factored credit note | | 502 | Self-billed factored credit note | | 503 | Credit note for an advance payment invoice |. Example: "380". Values: 380, 389, 393, 501, 386, 500, 384, 471, 472, 473, 261, 262, 381, 396, 502, 503 |
invoiceIssueDate | string (date) | No | Issue date of the referenced invoice. Required unless statusCode is 501. Example: "2024-03-15". Format: date |
sellerLegalId | string | No | Legal identifier (e.g. SIREN) of the invoice seller. Required unless statusCode is 501. Example: "123456789" |
sellerLegalIdScheme | string | No | ISO 6523 ICD scheme of the referenced invoice seller legal identifier. Required together with sellerLegalId. Example: "0002" |
reasonCode | string (enum) | No | Coded reason for the invoice lifecycle status. | Value | Meaning | | --- | --- | | JUSTIF_ABS | Supporting document missing or insufficient | | ROUTAGE_ERR | Routing error | | AUTRE | Other reason; provide an explanation in reasonNote | | COORD_BANC_ERR | Incorrect bank details | | TX_TVA_ERR | Incorrect VAT rate | | MONTANTTOTAL_ERR | Incorrect invoice total | | CALCUL_ERR | Invoice calculation error | | NON_CONFORME | Missing legal information | | DOUBLON | Duplicate invoice | | DEST_INC | Unknown recipient | | DEST_ERR | Incorrect recipient | | TRANSAC_INC | Unknown transaction | | EMMET_INC | Unknown issuer | | CONTRAT_TERM | Contract ended | | DOUBLE_FACT | Supply or service already invoiced on another invoice | | CMD_ERR | Incorrect or missing order number | | ADR_ERR | Incorrect electronic invoicing address | | SIRET_ERR | Incorrect or missing SIRET | | CODE_ROUTAGE_ERR | Incorrect or missing routing code | | REF_CT_ABSENT | Required contractual reference missing | | REF_ERR | Incorrect reference | | PU_ERR | Incorrect unit price | | REM_ERR | Incorrect discount | | QTE_ERR | Incorrect invoiced quantity | | ART_ERR | Incorrect invoiced item | | MODPAI_ERR | Incorrect payment terms | | QUALITE_ERR | Incorrect quality of delivered item | | LIVR_INCOMP | Incomplete or non-compliant delivery | | REJ_SEMAN | Rejected because of a semantic error | | REJ_UNI | Rejected by uniqueness control | | REJ_COH | Rejected by data-consistency control | | REJ_ADR | Rejected by addressing control | | REJ_CONT_B2G | Rejected by B2G business controls | | REJ_REF_PJ | Rejected because of an attachment-reference error | | REJ_ASS_PJ | Rejected because of an attachment-association error | | NON_TRANSMISE | Submitted but not transmitted because the recipient has no receiving platform | | IRR_VIDE_F | Inadmissible: a file in the submitted flow is empty | | IRR_TYPE_F | Inadmissible: a file in the flow has a wrong type or extension | | IRR_SYNTAX | Inadmissible: a file in the flow fails the syntax check | | IRR_TAILLE_PJ | Inadmissible: an attachment exceeds the size limit | | IRR_NOM_PJ | Inadmissible: an attachment name contains forbidden characters | | IRR_VID_PJ | Inadmissible: an attachment is empty | | IRR_EXT_DOC | Inadmissible: an attachment has a wrong extension | | IRR_TAILLE_F | Inadmissible: a file in the flow exceeds the maximum size | | IRR_ANTIVIRUS | Inadmissible: the flow fails the anti-virus check | | IRR_NOM_F | Inadmissible: a file name in the flow is invalid | | SUPPR_COMP_AVOIR | Public-sector refusal: withdrawn for offsetting against credit notes | | TRANSF_PMNT_REGIE | Public-sector refusal: transferred for payment through a régie | | CONTACT_ACHTR | Public-sector refusal: other reason, contact your buyer | | RETRAIT_MAN_SERV | Public-sector refusal reason, see the AFNOR XP Z12-012 reason code table | | ST_CT_NON_DECLAR | Public-sector refusal reason, see the AFNOR XP Z12-012 reason code table | The IRR_* codes are the reasons for an inadmissible file (501). The public-sector refusal codes are set by the public invoicing portal and only appear in CDARs you receive. When sending, statuses 200, 206, 207, 208, 210, 213 and 501 accept only the codes the French rules list for them (BR-FR-CDV-CL-09). A refusal (210) accepts TX_TVA_ERR, MONTANTTOTAL_ERR, CALCUL_ERR, NON_CONFORME, DOUBLON, DEST_ERR, TRANSAC_INC, EMMET_INC, CONTRAT_TERM, DOUBLE_FACT, CMD_ERR, ADR_ERR and REF_CT_ABSENT, so not AUTRE. Values: JUSTIF_ABS, ROUTAGE_ERR, AUTRE, COORD_BANC_ERR, TX_TVA_ERR, MONTANTTOTAL_ERR, CALCUL_ERR, NON_CONFORME, DOUBLON, DEST_INC, DEST_ERR, TRANSAC_INC, EMMET_INC, CONTRAT_TERM, DOUBLE_FACT, CMD_ERR, ADR_ERR, SIRET_ERR, CODE_ROUTAGE_ERR, REF_CT_ABSENT, REF_ERR, PU_ERR, REM_ERR, QTE_ERR, ART_ERR, MODPAI_ERR, QUALITE_ERR, LIVR_INCOMP, REJ_SEMAN, REJ_UNI, REJ_COH, REJ_ADR, REJ_CONT_B2G, REJ_REF_PJ, REJ_ASS_PJ, NON_TRANSMISE, IRR_VIDE_F, IRR_TYPE_F, IRR_SYNTAX, IRR_TAILLE_PJ, IRR_NOM_PJ, IRR_VID_PJ, IRR_EXT_DOC, IRR_TAILLE_F, IRR_ANTIVIRUS, IRR_NOM_F, SUPPR_COMP_AVOIR, TRANSF_PMNT_REGIE, CONTACT_ACHTR, RETRAIT_MAN_SERV, ST_CT_NON_DECLAR |
reason | string | No | Optional free-text status reason. This is distinct from the IncludedNote explanation required for reasonCode AUTRE |
reasonNote | string | No | Free-text comment in the status detail IncludedNote. Required when reasonCode is AUTRE. Example: "The invoice needs manual review." |
collectedAmounts | object[] | No | Collected amounts with VAT rates (TypeCode MEN). Required for status 212; at least one entry |
parsed.issueDate (Any of)
parsed.statusDate (Any of)
parsed.collectedAmounts properties
| Name | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Net collected amount (positive) or disbursed amount (negative), for status 212. Example: "12000.00" |
currency | string (enum) | Yes | ISO 4217 currency code of the collected amount. Example: "EUR". Values: XUA, AFN, DZD, ARS, AMD, AWG, AUD, AZN, BSD, BHD, THB, PAB, BBD, BYN, BZD, BMD, VES, VED, BOB, XBA, XBB, XBD, XBC, BRL, BND, BGN, BIF, CVE, CAD, KYD, XOF, XAF, XPF, CLP, XTS, COP, KMF, CDF, BAM, NIO, CRC, CUP, CZK, GMD, DKK, MKD, DJF, STN, DOP, VND, XCD, EGP, SVC, ETB, EUR, FKP, FJD, HUF, GHS, GIP, XAU, HTG, PYG, GNF, GYD, HKD, UAH, ISK, INR, IRR, IQD, JMD, JOD, KES, PGK, KWD, AOA, MMK, LAK, GEL, LBP, ALL, HNL, LRD, LYD, SZL, LSL, MGA, MWK, MYR, MUR, MXN, MXV, MDL, MAD, MZN, BOV, NGN, ERN, NAD, NPR, ANG, ILS, TWD, NZD, BTN, KPW, NOK, MRU, TOP, PKR, XPD, MOP, UYU, PHP, XPT, GBP, BWP, QAR, GTQ, ZAR, OMR, KHR, RON, MVR, IDR, RUB, RWF, SHP, SAR, XDR, RSD, SCR, SLE, XAG, SGD, PEN, SBD, KGS, SOS, TJS, SSP, LKR, XSU, SDG, SRD, SEK, CHF, SYP, BDT, WST, TZS, KZT, XXX, TTD, MNT, TND, TRY, TMT, AED, UGX, CLF, COU, UYW, UYI, USD, USN, UZS, VUV, CHE, CHW, KRW, YER, JPY, CNY, ZMW, ZWG, PLN |
vatPercent | string | Yes | VAT rate applicable to the collected amount. Example: "20.00" |
validation (One of)
Document Validation:
| Name | Type | Required | Description |
|---|---|---|---|
result | valid | invalid | not_supported | error | Yes | valid: the document passed every rule that applies to it. invalid: at least one rule was violated; see errors. not_supported: no ruleset is available for this document type, so nothing was checked. error: the validation service could not be reached or its answer could not be read. Example: "valid". Values: valid, invalid, not_supported, error |
errors | object[] | Yes | The findings the validation produced. Empty when the document is valid, and also when the result is not_supported or error |
validation.errors properties
| Name | Type | Required | Description |
|---|---|---|---|
ruleCode | string | null | No | The identifier of the rule that was violated, for example an EN 16931 or Peppol BIS business rule code. Null for findings that come from something other than a coded rule, such as a schema error. Example: "PEPPOL-EN16931-R010" |
errorMessage | string | Yes | What the rule expected, in the words of the ruleset that raised it |
errorLevel | string | Yes | How serious the finding is. Only findings the ruleset treats as errors make a document invalid. Example: "ERROR" |
fieldName | string | null | No | Where in the document the finding applies, usually as an XPath. Null when the finding is not tied to one place |
source | string | No | Which ruleset produced the finding, for example the syntax schema or a Peppol business rule set |
labels properties
| Name | Type | Required | Description |
|---|---|---|---|
colorHex | string | Yes | The colour the label is shown in, as a hex code. Example: "#3B82F6" |
externalId | string | null | Yes | Your own identifier for the label, if you set one. It is unique within the team, so you can address a label by the id your system already uses. Example: "erp-routing-inbox" |
id | string | Yes | The label's identifier, used wherever a label is assigned or unassigned. Example: "lbl_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
name | string | Yes | The label's name, as it is shown in the dashboard and returned on the documents and suppliers it is assigned to. Example: "ERP" |
reporting (One of)
French Reporting Status:
| Name | Type | Required | Description |
|---|---|---|---|
reportingStatus | accepted | pending_rectificative | filed | filed_rectificative | superseded | rejected | Yes | accepted: on file, inside its reporting period. pending_rectificative: arrived after the period was filed and will be carried by a corrective filing. filed / filed_rectificative: carried on a filing transmitted to the tax administration; not final until outcomeCode is 300, see final. superseded: replaced by a correction or cancelled. rejected: refused by the tax administration; see outcomeCode. Values: accepted, pending_rectificative, filed, filed_rectificative, superseded, rejected |
final | boolean | Yes | True once nothing more will be heard about the report: filed or filed_rectificative with outcomeCode 300, superseded, or rejected. A filed report whose outcome is still empty or 500 is not final and keeps being refreshed |
receivedAt | string | null | Yes | When the report reached the reporting service |
periodStart | string | null | Yes | First day of the reporting period the report belongs to |
periodEnd | string | null | Yes | Last day of the reporting period; the cutoff for on-time filing |
submissionId | string | null | Yes | The period filing the report was carried on, once assembled |
outcomeCode | string | null | Yes | The tax administration's outcome code for the filing the report is carried on. It moves independently of reportingStatus: empty at first, then 500 while the deposit is being processed, then 300 once it is accepted. 501 means the deposit was refused and has to be resolved with support. A filed report is final only with 300 |
outcomeAt | string | null | Yes | When the tax administration returned its outcome |
checkedAt | string | null | Yes | When the status was last refreshed from the reporting service |
simulated | boolean | Yes | True for playground and test-network reports, which are recorded but never filed |
deliveries properties
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The delivery ID. It identifies this delivery in document.delivery_status_changed webhook events. Example: "dlv_01JQZ8X0M4T7RB6K9V2NDHW3PA" |
channel | peppol | email | Yes | How the document was sent to this address. Example: "peppol". Values: peppol, email |
address | string | Yes | The Peppol address or email address the document was sent to. Example: "0208:0428643097" |
status | pending | delivered | failed | Yes | pending: the channel accepted the document and has not confirmed arrival. delivered: the channel confirmed arrival; for Peppol the recipient's access point acknowledged the document, for email the recipient's mail server accepted the message. failed: the document did not arrive; for email the message bounced or was refused. See failure. Example: "delivered". Values: pending, delivered, failed |
statusChangedAt | string | Yes | When the delivery reached its current status |
failure | Delivery Failure | null | Yes |
references | object | Yes | The identifiers the delivery is known by on its channel: the AS4 and envelope IDs for peppol deliveries, the mail service's messageId for email deliveries |
deliveries.failure (One of)
Delivery Failure:
| Name | Type | Required | Description |
|---|---|---|---|
category | recipient_not_found | document_not_supported | validation | transport | recipient_rejected | duplicate | other | Yes | Why the delivery failed, in the same terms for every channel and access point: recipient_not_found (the address is not registered on the network, or the mailbox does not exist), document_not_supported (the recipient does not receive this document type), validation (the document was refused by a rule), transport (it could not be transmitted, or the mail server did not take the message), recipient_rejected (the recipient or their server refused it, for email a block or spam complaint), duplicate or other. Example: "validation". Values: recipient_not_found, document_not_supported, validation, transport, recipient_rejected, duplicate, other |
message | string | null | Yes | What went wrong, as the channel or access point described it |
providerCode | string | null | Yes | The access point's or mail service's own code for the failure, when it reported one: an access point error code, or a bounce type such as HardBounce. Example: "TXE-1005" |
deliveries.references properties
| Name | Type | Required | Description |
|---|---|---|---|
peppolMessageId | string | null | No | The AS4 message ID of the transmission |
peppolConversationId | string | null | No | The AS4 conversation ID of the transmission |
envelopeId | string | null | No | The envelope ID (SBDH instance identifier) of the transmission |
messageId | string | null | No | The mail service's message ID of the email, for email deliveries. It is the ID a bounce or delivery notification from the mail service refers to. Null when the delivery predates message tracking |