Models
Self Billing Invoice to send
Self billing invoice to send to a recipient
Properties
| Name | Type | Required | Description |
|---|---|---|---|
invoiceNumber | string | Yes | The number the seller assigned to the invoice. Example: "INV-2024-001" |
issueDate | string | null | No | If not provided, the issue date will be the current date. Example: "2024-03-20". Format: date |
dueDate | string | null | No | If not provided, the due date will be 1 month from the issue date. 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: "CC-4120" |
purchaseOrderReference | string | null | No | The buyer's purchase order number (BT-13), written to the order reference. Example: "4500012345" |
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 | Party | null | No |
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 | Payment Terms | null | No |
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 | VAT totals auto calculation | null |
attachments | object[] | null | No | Optional attachments to the invoice |
currency | object | No | The currency of the invoice. Defaults to EUR. Default: EUR. Example: "EUR" |
countrySpecific | Country Specific Billing | null | No |
seller properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | Enterprise Number Scheme | null | No |
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" |
seller.enterpriseNumberScheme (One of)
buyer (One of)
Party:
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | The VAT number including its country prefix, for example BE0123456789. Example: "BE1234567894" |
enterpriseNumberScheme | Enterprise Number Scheme | null | No |
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" |
buyer.enterpriseNumberScheme (One of)
delivery (One of)
Delivery:
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | No | The date of the delivery. Example: "2025-03-20". Format: date |
locationIdentifier | Location Identifier | null | No |
location | object | No | |
recipientName | string | No | The name of the party to which the goods and services are delivered. Example: "Company Ltd." |
delivery.locationIdentifier (One of)
Location Identifier:
The identifier of a delivery location within a registered scheme. Schemes can be found here.
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
delivery.location properties
| Name | Type | Required | Description |
|---|---|---|---|
city | string | null | No | Example: "Brussels" |
country | string | Yes | Example: "BE" |
postalZone | string | null | No | Example: "1000" |
street | string | null | No | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
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 |
paymentTerms (One of)
Payment Terms:
Optional payment terms.
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | The payment terms as free text. Example: "Net 30" |
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 | Standard Id | null | No |
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 |
lines.standardId (One of)
Standard Id:
The standard identifier of the item based on a registered scheme. Schemes can be found here.
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0160" |
identifier | string | Yes | Example: "10986700" |
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" |
lines.additionalItemProperties properties
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Example: "Color" |
value | string | Yes | Example: "Red" |
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" |
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" |
lines.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | object | No | Default: S |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
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 |
discounts.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | object | No | Default: S |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
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 |
surcharges.vat properties
| Name | Type | Required | Description |
|---|---|---|---|
category | object | No | Default: S |
percentage | string | Yes | The VAT rate as a percentage, for example 21.00. Example: "21.00" |
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" |
vat (Any 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 |
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 |
VAT totals auto calculation:
Recommand will automatically calculate the VAT totals based on the document lines. For invoices that are exempt from VAT, you can provide the exemption reason or reason code here to inform the recipient of the reason why the amount is exempt from VAT.
| Name | Type | Required | Description |
|---|---|---|---|
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 |
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" |