Models
Invoice to send
Invoice to send to a recipient
Properties
| Name | Type | Required | Description |
|---|---|---|---|
invoiceNumber | string | Yes | 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 | Example: "Thank you for your business" |
buyerReference | string | null | No | 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 | Party | null | No |
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 | |
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 | VAT totals auto calculation | null |
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 |
seller (One of)
Party:
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | 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 | Example: "1234567894" |
name | string | Yes | Example: "Example Company" |
street | string | Yes | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | Yes | Example: "Brussels" |
postalZone | string | Yes | Example: "1000" |
country | string | Yes | 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 properties
| Name | Type | Required | Description |
|---|---|---|---|
vatNumber | string | null | No | 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 | Example: "1234567894" |
name | string | Yes | Example: "Example Company" |
street | string | Yes | Example: "Example Street 1" |
street2 | string | null | No | Example: "Suite 100" |
city | string | Yes | Example: "Brussels" |
postalZone | string | Yes | Example: "1000" |
country | string | Yes | 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" |
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." |
delivery.locationIdentifier properties
| Name | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Example: "0088" |
identifier | string | Yes | Example: "123456789" |
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" |
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 | 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 | Default: ``. Example: "INV-2026-001" |
iban | string | Yes | 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 properties
| Name | Type | Required | Description |
|---|---|---|---|
note | string | Yes | 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 | Default: ``. Example: "Consulting Services" |
description | string | null | No | 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 | Decimal number as a string with flexible precision. Default: 1.00. Example: "21.00" |
unitCode | string | No | Recommended unit codes can be found here. Default: C62. Example: "HUR" |
netPriceAmount | string | Yes | Decimal number as a string with flexible precision. Example: "21.00" |
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 properties
| 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 | 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 | Decimal number as a string with 2 decimal places. 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 | 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 | Decimal number as a string with 2 decimal places. 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 | 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 | Decimal number as a string with 2 decimal places. 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 | Decimal number as a string with 2 decimal places. Example: "21.00" |
subtotals | object[] | Yes |
vat.subtotals properties
| Name | Type | Required | Description |
|---|---|---|---|
taxableAmount | string | Yes | Decimal number as a string with 2 decimal places. Example: "21.00" |
vatAmount | string | Yes | Decimal number as a string with 2 decimal places. 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 | Decimal number as a string with 2 decimal places. 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 | 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 | Example: "contract.pdf" |
description | string | null | No | Example: "Signed contract" |
embeddedDocument | string | null | No | base64 encoded document |
url | string | null | No | Example: "https://example.com/contract.pdf" |
Used by
Attachment
Previous Page
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.