Credit Note Request
Complete field reference for the CreditNoteDocument schema.
The CreditNoteDocument schema (@type = "CreditNoteDocument") is used with the Send a document from a JSON structure endpoint.
CreditNoteDocument
| Field | Type | Description |
|---|---|---|
accountingCurrency | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
additionalIdentifiers | object | Escape-hatch for format-specific identifiers not yet mapped to a typed field. Empty if none. |
Attachment[] | BG-24 — Embedded supporting documents / binary attachments (e.g. a PDF rendition). Empty if none. | |
contentrequired | string | BG-24 embedded binary content, Base64-encoded (BT-125) |
contentTyperequired | string | BG-24 attachment MIME type — must be application/pdf for v1.0 |
description | string | BG-24 human-readable document description (BT-123) |
filenamerequired | string | BG-24 attachment file name (e.g. invoice-2026-001.pdf) |
businessProcessType | string | BT-23 — Business process type the document belongs to. |
| required | Party | |
additionalLegalInfo | string | BT-33 — Additional legal information about the party (e.g. share capital, legal form). |
| required | Address | |
additionalStreet | string | BT-162 / BT-163 — Additional address line. |
cityrequired | string | BT-37 (seller) / BT-52 (buyer) — City / town. |
countryCoderequired | string | ISO 3166-1 alpha-2 country code (BT-40, BT-55, BT-159). Serialized in JSON as the two-letter country code, which is the enum constant name, e.g. "LU", "DE", "FR". |
countrySubdivision | string | BT-39 (seller) / BT-54 (buyer) — Country subdivision (region / state / province). |
postCoderequired | string | BT-38 (seller) / BT-53 (buyer) — Post code / ZIP. |
street1required | string | BT-35 (seller) / BT-50 (buyer) — Address line 1 (street and number). |
street2 | string | BT-36 / BT-51 — Address line 2. |
Contact | ||
email | string | BT-43 (seller) / BT-58 (buyer) — Contact email address. |
name | string | BT-41 (seller) / BT-56 (buyer) — Contact point name. |
telephone | string | BT-42 (seller) / BT-57 (buyer) — Contact telephone number. |
electronicAddressrequired | string | BT-34 (seller) / BT-49 (buyer) — Electronic address: the Peppol participant value, paired with electronicAddressSchemeId. |
electronicAddressSchemeIdrequired | string | Peppol EAS (Electronic Address Scheme, iso6523-actorid-upis) code list identifying the scheme of a participant's electronic address. Serialized in JSON as the numeric EAS code, e.g. "9938" = LU:VAT, "0211" = IT:IVA, "0235" = AE:TIN, "0088" = GLN; for backward compatibility the enum constant name (colon replaced by underscore, e.g. "LU_VAT") is also accepted on deserialization. |
identifier | string | BT-29 (seller) / BT-46 (buyer) — Party identifier (with optional scheme). |
legalRegistrationId | string | BT-30 (seller) / BT-47 (buyer) — Legal registration identifier (e.g. commercial register no.). |
namerequired | string | BT-27 (seller) / BT-44 (buyer) — Party legal name. |
taxRegistration | string | BT-32 — Seller tax registration identifier (where a non-VAT tax number applies). |
tradingName | string | BT-28 (seller) / BT-45 (buyer) — Trading name, if different from the legal name. |
vatIdrequired | string | BT-31 (seller) / BT-48 (buyer) — VAT identifier. |
buyerAccountingReference | string | BT-19 — Buyer accounting reference (e.g. accounting cost / GL account). |
buyerReference | string | BT-10 — Buyer reference (e.g. cost centre); often mandatory for B2G. |
contractReference | string | BT-12 — Contract reference. |
creditNoteReasonCode | string | BTAE-03 — Credit note reason code (jurisdiction-specific). Mandatory for PINT AE credit notes (from the 'Reasons for credit note' code list); ignored where the jurisdiction does not define it. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
Delivery | ||
Address | ||
additionalStreet | string | BT-162 / BT-163 — Additional address line. |
cityrequired | string | BT-37 (seller) / BT-52 (buyer) — City / town. |
countryCoderequired | string | ISO 3166-1 alpha-2 country code (BT-40, BT-55, BT-159). Serialized in JSON as the two-letter country code, which is the enum constant name, e.g. "LU", "DE", "FR". |
countrySubdivision | string | BT-39 (seller) / BT-54 (buyer) — Country subdivision (region / state / province). |
postCoderequired | string | BT-38 (seller) / BT-53 (buyer) — Post code / ZIP. |
street1required | string | BT-35 (seller) / BT-50 (buyer) — Address line 1 (street and number). |
street2 | string | BT-36 / BT-51 — Address line 2. |
deliveryDate | date | BG-13 actual delivery date (BT-72) |
locationIdentifier | string | BG-13 deliver-to location identifier (BT-71) |
locationIdentifierSchemeId | string | BG-13 deliver-to location identifier scheme (BT-71-1) |
partyName | string | BG-13 deliver-to party name (BT-70) |
despatchAdviceReference | string | BT-16 — Despatch advice reference. |
documentIdrequired | string | BT-1 — Credit note number. Unique identifier from the sender. |
Allowance[] | BG-20 — Document-level allowances (discounts). Empty if none. | |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
percentage | number | BG-20/BG-27 allowance percentage (BT-94 / BT-138) |
reasonCode | string | BG-20/BG-27 allowance reason code (BT-98 / BT-140) |
reasonText | string | BG-20/BG-27 allowance reason text (BT-97 / BT-139) |
vatCategoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
vatRate | number | BG-20/BG-27 allowance VAT rate (BT-96) |
Charge[] | BG-21 — Document-level charges (fees). Empty if none. | |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
percentage | number | BG-21/BG-28 charge percentage (BT-101 / BT-143) |
reasonCode | string | BG-21/BG-28 charge reason code (BT-105 / BT-145) |
reasonText | string | BG-21/BG-28 charge reason text (BT-104 / BT-144) |
vatCategoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
vatRate | number | BG-21/BG-28 charge VAT rate (BT-103) |
dueDate | date | BT-9 — Payment due date. |
FacturXExtensions | ||
profilerequired | string | Factur-X / ZUGFeRD 2.x conformance profile, in increasing order of completeness: MINIMUM, BASIC_WL (basic without invoice lines), BASIC, EN16931 (EN 16931 compliant), EXTENDED. |
renderHumanReadablePdf | boolean | Whether to render a human-readable PDF representation of the invoice. |
FatturaPaExtensions | ||
codiceDestinatario | string | Recipient SDI destination code (Codice Destinatario) for routing the invoice through the Sistema di Interscambio. |
codiceFiscaleSender | string | Sender's Italian fiscal code (Codice Fiscale). |
FatturaPaContractRef | ||
codiceCIG | string | Tender identification code (CodiceCIG), mandatory for public-administration invoices. |
codiceCUP | string | Single project code (CodiceCUP), mandatory for public-administration invoices. |
datarequired | date | Contract date (Data). |
idDocumentorequired | string | Contract document identifier (IdDocumento). |
FatturaPaDdtRef | ||
dataDdtrequired | date | Transport document date (DataDDT). |
numeroDdtrequired | string | Transport document number (NumeroDDT). |
esigibilitaIVA | string | FatturaPA EsigibilitaIVA code list defining the VAT chargeability point: I (immediate), D (deferred), or S (split payment / scissione dei pagamenti). |
modalitaPagamento | string | FatturaPA ModalitaPagamento code list (MP01..MP23) identifying the Italian payment method. |
naturaPerTaxBreakdown | string[] | VAT-exemption nature codes (Natura, N1..N7) applied per tax breakdown line, mandatory when the VAT rate is zero. |
pecDestinatario | string | Recipient certified e-mail address (PEC) used as an alternative delivery channel when no Codice Destinatario applies. |
regimeFiscalerequired | string | FatturaPA RegimeFiscale code list (RF01..RF19) identifying the sender's Italian tax regime. |
splitPayment | boolean | Whether split payment (scissione dei pagamenti) applies, meaning the buyer pays VAT directly to the tax authority. |
tipoDocumentorequired | string | FatturaPA TipoDocumento code list (TD01..TD29) identifying the Italian SDI document type. Reference: Agenzia delle Entrate, FatturaPA v1.9 (April 2025). |
invoicedObjectIdentifier | string | BT-18 — Invoiced object identifier. |
issueDaterequired | date | BT-2 — Credit note issue date. |
| required | LineItem[] | BG-25 — Credit note lines. At least one line is required. |
Allowance[] | BG-27 — Invoice line allowances (discounts). Empty if none. | |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
percentage | number | BG-20/BG-27 allowance percentage (BT-94 / BT-138) |
reasonCode | string | BG-20/BG-27 allowance reason code (BT-98 / BT-140) |
reasonText | string | BG-20/BG-27 allowance reason text (BT-97 / BT-139) |
vatCategoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
vatRate | number | BG-20/BG-27 allowance VAT rate (BT-96) |
NameValue[] | BG-32 — Item attributes (additional name/value characteristics). Empty if none. | |
namerequired | string | Attribute name / item property name (BT-160) |
valuerequired | string | Attribute value / item property value (BT-161) |
buyerAccountingRef | string | BT-133 — Invoice line buyer accounting reference. |
buyerItemId | string | BT-156 — Buyer's item identifier. |
Charge[] | BG-28 — Invoice line charges (fees). Empty if none. | |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
percentage | number | BG-21/BG-28 charge percentage (BT-101 / BT-143) |
reasonCode | string | BG-21/BG-28 charge reason code (BT-105 / BT-145) |
reasonText | string | BG-21/BG-28 charge reason text (BT-104 / BT-144) |
vatCategoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
vatRate | number | BG-21/BG-28 charge VAT rate (BT-103) |
classificationId | string | BT-158 — Item classification identifier (e.g. CPV / UNSPSC). |
countryOfOrigin | string | ISO 3166-1 alpha-2 country code (BT-40, BT-55, BT-159). Serialized in JSON as the two-letter country code, which is the enum constant name, e.g. "LU", "DE", "FR". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
idrequired | string | BT-126 — Invoice line identifier. |
itemDescription | string | BT-154 — Item description. |
itemNamerequired | string | BT-153 — Item name. |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
note | string | BT-127 — Invoice line note (free text). |
objectIdentifier | string | BT-128 — Invoice line object identifier. |
periodEnd | date | BT-135 — Invoice line period end date. |
periodStart | date | BT-134 — Invoice line period start date. |
priceBaseQuantity | number | BT-149 — Item price base quantity (number of units the price applies to). |
priceBaseQuantityUnit | string | UN/ECE Recommendation 20 unit of measure code (BT-130, BT-150), e.g. C62 piece, HUR hour, KGM kilogram, MTR metre. Serialized in JSON as the Rec 20 code, which is the enum constant name, e.g. "C62", "HUR". |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
purchaseOrderLineRef | string | BT-132 — Referenced purchase order line. |
quantityrequired | number | BT-129 — Invoiced quantity. |
sellerItemId | string | BT-155 — Seller's item identifier. |
standardItemId | string | BT-157 — Item standard identifier (with scheme, e.g. GTIN). |
unitCoderequired | string | UN/ECE Recommendation 20 unit of measure code (BT-130, BT-150), e.g. C62 piece, HUR hour, KGM kilogram, MTR metre. Serialized in JSON as the Rec 20 code, which is the enum constant name, e.g. "C62", "HUR". |
vatCategoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
vatRaterequired | number | BT-152 — Invoiced item VAT rate (percentage). |
note | string | BT-22 — Note (free-text remarks). |
originalInvoiceDaterequired | date | BT-26 — Preceding invoice issue date (date of the original invoice). |
originalInvoiceNumberrequired | string | BT-25 — Preceding invoice reference: number of the original invoice this credit note relates to. |
PaymentInfo | ||
BankAccount[] | BG-17 credit-transfer bank accounts (BT-84..86); empty when not applicable | |
accountName | string | Payment account name (BT-85) |
bic | string | Payment service provider identifier / BIC (BT-86) |
ibanrequired | string | Payment account identifier / IBAN for credit transfer (BT-84) |
paymentMeansCoderequired | string | UNCL4461 payment means code (BT-81), e.g. 30 credit transfer, 58 SEPA credit transfer, 48 card, 49 direct debit. Serialized in JSON as the enum constant name (e.g. "CREDIT_TRANSFER", "SEPA_CREDIT_TRANSFER"); the numeric code is exposed separately via code(). |
paymentMeansText | string | BG-16 payment means text (BT-82) |
remittanceInformation | string | BG-16 remittance / payment reference (BT-83) |
paymentTermsText | string | BT-20 — Payment terms in free text. |
PeppolExtensions | ||
profileIdOverride | string | Optional override for the PEPPOL profile identifier. |
receiverSchemeIdOverride | string | Peppol EAS (Electronic Address Scheme, iso6523-actorid-upis) code list identifying the scheme of a participant's electronic address. Serialized in JSON as the numeric EAS code, e.g. "9938" = LU:VAT, "0211" = IT:IVA, "0235" = AE:TIN, "0088" = GLN; for backward compatibility the enum constant name (colon replaced by underscore, e.g. "LU_VAT") is also accepted on deserialization. |
senderSchemeIdOverride | string | Peppol EAS (Electronic Address Scheme, iso6523-actorid-upis) code list identifying the scheme of a participant's electronic address. Serialized in JSON as the numeric EAS code, e.g. "9938" = LU:VAT, "0211" = IT:IVA, "0235" = AE:TIN, "0088" = GLN; for backward compatibility the enum constant name (colon replaced by underscore, e.g. "LU_VAT") is also accepted on deserialization. |
Money | ||
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
projectReference | string | BT-11 — Project reference. |
purchaseOrderReference | string | BT-13 — Purchase order reference. |
receivingAdviceReference | string | BT-15 — Receiving advice reference. |
salesOrderReference | string | BT-14 — Sales order reference. |
| required | Party | |
additionalLegalInfo | string | BT-33 — Additional legal information about the party (e.g. share capital, legal form). |
| required | Address | |
additionalStreet | string | BT-162 / BT-163 — Additional address line. |
cityrequired | string | BT-37 (seller) / BT-52 (buyer) — City / town. |
countryCoderequired | string | ISO 3166-1 alpha-2 country code (BT-40, BT-55, BT-159). Serialized in JSON as the two-letter country code, which is the enum constant name, e.g. "LU", "DE", "FR". |
countrySubdivision | string | BT-39 (seller) / BT-54 (buyer) — Country subdivision (region / state / province). |
postCoderequired | string | BT-38 (seller) / BT-53 (buyer) — Post code / ZIP. |
street1required | string | BT-35 (seller) / BT-50 (buyer) — Address line 1 (street and number). |
street2 | string | BT-36 / BT-51 — Address line 2. |
Contact | ||
email | string | BT-43 (seller) / BT-58 (buyer) — Contact email address. |
name | string | BT-41 (seller) / BT-56 (buyer) — Contact point name. |
telephone | string | BT-42 (seller) / BT-57 (buyer) — Contact telephone number. |
electronicAddressrequired | string | BT-34 (seller) / BT-49 (buyer) — Electronic address: the Peppol participant value, paired with electronicAddressSchemeId. |
electronicAddressSchemeIdrequired | string | Peppol EAS (Electronic Address Scheme, iso6523-actorid-upis) code list identifying the scheme of a participant's electronic address. Serialized in JSON as the numeric EAS code, e.g. "9938" = LU:VAT, "0211" = IT:IVA, "0235" = AE:TIN, "0088" = GLN; for backward compatibility the enum constant name (colon replaced by underscore, e.g. "LU_VAT") is also accepted on deserialization. |
identifier | string | BT-29 (seller) / BT-46 (buyer) — Party identifier (with optional scheme). |
legalRegistrationId | string | BT-30 (seller) / BT-47 (buyer) — Legal registration identifier (e.g. commercial register no.). |
namerequired | string | BT-27 (seller) / BT-44 (buyer) — Party legal name. |
taxRegistration | string | BT-32 — Seller tax registration identifier (where a non-VAT tax number applies). |
tradingName | string | BT-28 (seller) / BT-45 (buyer) — Trading name, if different from the legal name. |
vatIdrequired | string | BT-31 (seller) / BT-48 (buyer) — VAT identifier. |
| required | TaxBreakdown[] | BG-23 — VAT breakdown per category/rate. At least one entry is required. |
categoryCoderequired | string | UNCL5305 VAT category code (BT-118, BT-151), e.g. S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G free export, O outside scope, L Canary Islands IGIC, M Ceuta and Melilla (plus PINT MY jurisdiction codes). Serialized in JSON as the category code, which is the enum constant name, e.g. "S", "AE". |
exemptionReasonCode | string | BT-121 — VAT exemption reason code. |
exemptionReasonText | string | BT-120 — VAT exemption reason text. |
raterequired | number | BT-119 — VAT category rate (percentage). |
| required | Money | |
amountrequired | number | Monetary amount. Up to 2 decimals for totals, up to 4 for unit prices / tax bases. |
currencyrequired | string | ISO 4217 currency code (BT-5, BT-6). Serialized in JSON as the three-letter ISO 4217 alphabetic code, which is the enum constant name, e.g. "EUR", "USD", "CHF". |
tenderOrLotReference | string | BT-17 — Tender or lot reference. |
typeCoderequired | string | UN/CEFACT 1001 document type code (BT-3), e.g. 380 commercial invoice, 381 credit note, 384 corrected invoice, 386 prepayment invoice, 389 self-billed invoice. Serialized in JSON as the enum constant name (e.g. "COMMERCIAL_INVOICE", "CREDIT_NOTE"); the numeric code is exposed separately via code(). |
vatPointDate | date | BT-7 — VAT point date: the date when VAT becomes accountable. |
vatPointDateCode | string | BT-8 — VAT point date code, when expressed as a code instead of a date. |
XRechnungExtensions | ||
b2gMode | boolean | Whether to enable German B2G mode. |
LeitwegId | ||
valuerequired | string | The Leitweg-ID value, e.g. 04011000-12345-37. |