Extra Fields : Extend Content (Header)
Custom Fields - Extra Fields - More Fields - Header
About Extra Fields
Billit provides a JSON structure with a wide range of basic fields. Additional fields might be needed for more advanced billing scenario's, or to use it in international networks (Peppol and non-Peppol).
You can add these fields for both Invoices and Creditnote.
The allowed values for Income can be found in the lists below.
Order (Header Level) - Comments and Notes
If the want to add free text information on Header level, then you have 2 options.
| Key (Header) | Where in Json | Result in Peppol UBL | Result on Billit generated Human Readable |
|---|---|---|---|
| Invoice.Note | Header - Custom Fields | Note | Not displayed on PDF |
| Comments | Header | Note | Will be displayed on PDF |
Other remarks:
- Use only one of the values in one document : use Invoice.Note or Comments, NOT both
- Billit Human Readable will only be generated if you did not include your own PDF
Multiple text information elements can be combined in one field. Example how to put it in the Json body:
"Comments": "test comment 1. Test comment 2. Test comment 3. Test comment 4", "Comments": "test comment 1
test comment 2
test comment 3
test comment 4", Order (Header Level)
| Key (Header) | Linked Info When Peppol | Extra Information |
|---|---|---|
| Invoice.TaxPointDate | TaxPointDate | Mention date if if the VAT tax point date is different from the Invoice issue date |
| Invoice.InvoicePeriod.StartDate | InvoicePeriod | Start date of the services (header level) |
| Invoice.InvoicePeriod.EndDate | InvoicePeriod | End date of the services (header level) |
| Invoice.ContractDocumentReference.ID.Text | ContractDocRef | Contract number |
| Invoice.ProjectReference.ID.Text | ProjectReference | Project Identification |
| Invoice.AccountingCost | AccountingCost | Info for the Buyer about how to put in the Accounts (CostID, General Ledger (G/L, "grootboek"), other reference on request of buyer). This will appear on header as "AccountingCost". Free format, but just the refernence is recommended. |
| PaymentTerms | PaymentTerms/Note | Additional free text description for Payment Terms. Here you can add various payment terms descriptions |
| PaymentMeansCode | PaymentMeansCode | Billit will automatically generate a payment means code. But if a specific code is required, it can be set. It must be a valid code. |
| Invoice.OrderReference.SalesOrderID.Text | SalesOrderID | Sales order number (Number of the order registered by the Seller) |
| Invoice.DespatchDocumentReference.ID.Text | DespatchDocRef | Number of the Delivery Note |
| AdditionalDocumentReference | AdditionalDocumentReference | Add one or more document references, this is free additional information on header level, more info in separate segment below |
Order : Delivery Location (Header Level - Income)
For what it can be used:
- Set a delivery location ID. This can be useful to give an specific numberic value known by the customer. In addition it can be a standardised value (GLN number for delivery location)
- Set the Name and the Address Details, result :
- It will appear in a correct way in the output file (typically UBL)
- It will not appear on MyBillit Screen or on Billit Human Readable and in the customer info
It can be important the specify where goods are delivered. Below more information how to use it.
| Key (Header) | Linked Info When Peppol | Extra Information |
|---|---|---|
| Invoice.Delivery.DeliveryLocation.ID.Text | Link | A number or reference for the delivery location |
| Invoice.Delivery.DeliveryLocation.ID.SchemeID | Link | A structured value, for GLN number this is 0088 |
| Invoice.Delivery.DeliveryLocation.PostalAddress.StreetName | Link | Street delivery location |
| Invoice.Delivery.DeliveryLocation.Address. AdditionalStreetName | Link | Second streed field |
| Invoice.Delivery.DeliveryLocation.Address.CityName | Link | Delivery City |
| Invoice.Delivery.DeliveryLocation.Address.PostalZone | Link | Delivery Zip |
| Invoice.Delivery.DeliveryLocation.Address.CountrySubentity | Link | Delivery country sub entity (e.g. province) |
| Invoice.Delivery.DeliveryLocation.Address.Country. IdentificationCode.Text | Link | Delivery Country code (e.g. BE, FR, NL. Remark : when using this section, country is **mandatory **! |
Exemples of Delivery location identification (one with GLN number, one without) :
"CustomFields" : {
"Invoice.Delivery.DeliveryLocation.ID.Text": "5430009861001", //(GLN number)
"Invoice.Delivery.DeliveryLocation.ID.SchemeID": "0088" //0088 refers to GLN
},"CustomFields" : {
"Invoice.Delivery.DeliveryLocation.ID.Text": "96587452", //This is a specific delivery location number, not according to a standard such as GLN)
},Example with full delivery address:
"CustomFields" : {
"Invoice.Delivery.DeliveryLocation.ID.Text": "543000985477", //Delivery Location Number (GLN number)
"Invoice.Delivery.DeliveryLocation.ID.SchemeID": "0088", //0088 is referring to scheme ID of type GLN
"Invoice.Delivery.DeliveryLocation.Address.Country.IdentificationCode.Text": "BE",
"Invoice.Delivery.DeliveryLocation.Address.PostalZone": "9000",
"Invoice.Delivery.DeliveryLocation.Address.StreetName": "Octrooiplein 1b",
"Invoice.Delivery.DeliveryLocation.Address.AdditionalStreetName": "Extra info street",
"Invoice.Delivery.DeliveryLocation.Address.CityName": "Gent",
"Invoice.Delivery.DeliveryLocation.Address.CountrySubentity": "Oost-Vlaanderen",
"Invoice.Delivery.DeliveryParty.PartyName.Name": "Billit Reception of Goods Gent"
},Additional Document Reference
About Additional Document Reference (Header):
- When sending over Peppol, one additional document reference is used for including the file attachment (e.g. PDF).
- Multiple Additional Document References can be added.
- Each Reference can contain just the value or also a signification of the value
- This can be useful when you have no other structured field to put the information in
- Background peppol documentation : AdditionalDocumentReference
Example Below with 3 additional document references in custom field.
"CustomFields" : {
"AdditionalDocumentReference1": "Customer Number 1236547",
"AdditionalDocumentReference2": "International Transport Document 2565781",
"AdditionalDocumentReference3": "Total Weight 422 kg"
}, <cac:AdditionalDocumentReference>
<cbc:ID>BE0454298213_2460330_900-DocRef3.pdf</cbc:ID>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="BE0454298213_2460330_900-DocRef3.pdf">JVBERi0xLjUKJb66yVsNQuIoEhnxlbhSurfJuPgq5hj9vEIAnnhcM+69BaP3Dtq2bPQW1zmuvRCxWRD2/QSXMbG0i7p5rjwqLHNL ... SxuJk2YcJ8ZrI2mXnFJ2N3yXSv0Dgj5bugplbmRzdHJlYW0KZW5kb2JqCnN0YXJ0eHJlZgoxNTYxMTIKJSVFT0YK</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
<cbc:ID>Customer Number 1236547</cbc:ID>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
<cbc:ID>International Transport Document 2565781</cbc:ID>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
<cbc:ID>Total Weight 422 kg</cbc:ID>
</cac:AdditionalDocumentReference>Additional Contact Information on Header Level (Income / Cost)
Within the Basic Json you can include a lot of information about Customer and Supplier contacts.
Optionally, Specific fields are available:
- What : Contact info : Name, Email, Telephone for Supplier (sender) and Customer (Receiver)
- Specific behaviour:
- When these data are included in the posted invoice data, they do not update the customer data stored in Billit.
- The contact data do only apply to this invoice
- You can still communicatie in the customer segment the regular customer section, but the contact data in the custom section will have priority for this invoice
- The custom contact info will appear in the output einvoice file (typically UBL
- Contact data will not appear in on the Billit Human Readable (you might use you own human readable)
- Type of use:
- supported : in UBL the contact details of supplier and/or customer will be filled
- not supported : use the email address of customer to send via email
Field information:
| Key (Header) | Linked Info When Peppol | |
|---|---|---|
| Invoice.AccountingSupplierParty.Party.Contact.Name | Link | |
| Invoice.AccountingSupplierParty.Party.Contact.Telephone | Link | |
| Invoice.AccountingSupplierParty.Party.Contact.ElectronicMail | Link | |
| Invoice.AccountingCustomerParty.Party.Contact.Name | Link | |
| Invoice.AccountingCustomerParty.Party.Contact.Telephone | Link | |
| Invoice.AccountingCustomerParty.Party.Contact.ElectronicMail | Link |
Example:
"CustomFields" : {
"Invoice.AccountingSupplierParty.Party.Contact.Name":"Piet Pieters2",
"Invoice.AccountingSupplierParty.Party.Contact.Telephone":"0385478999",
"Invoice.AccountingSupplierParty.Party.Contact.ElectronicMail": "[email protected]",
"Invoice.AccountingCustomerParty.Party.Contact.Name": "Jean Dupont2",
"Invoice.AccountingCustomerParty.Party.Contact.Telephone": "0385478888",
"Invoice.AccountingCustomerParty.Party.Contact.ElectronicMail": "[email protected]"
}, Tax Representative Party (Header level - Income)
In case of international trade there can be a Tax Representative Party who is different from the Seller. Information about this Party can also be included.
| Value | Linked Info When Peppol |
|---|---|
| Invoice.TaxRepresentativeParty.PartyName.Name (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.StreetName (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.AdditionalStreetName (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.CityName (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.PostalZone (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.CountrySubentity (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.AddressLine.Line (Text) | Link |
| Invoice.TaxRepresentativeParty.PostalAddress.Country.IdentificationCode (Text) | Link |
Not yet operational:
| Invoice.TaxRepresentativeParty.PartyTaxScheme.CompanyID (Text) |
|---|
| Invoice.TaxRepresentativeParty.PartyTaxScheme.TaxScheme.ID |
Example Json with Extra / Custom Fields (Income)
See below content of Custom Fields (Income) on Header Level and Detail Line Level.
Example 1 is all main fields, Example 2 is focused on Tax Representative Party.
{
"OrderType": "Invoice",
"OrderDirection": "Income",
"OrderNumber": "QS-002",
"OrderDate": "2025-05-05",
"ExpiryDate": "2025-06-30",
"Reference": "8541518745 ", //PO Reference of the buyer
"OrderTitle": "Other Reference 45215487", // Buyer Reference : Another reference of the buyer
"CustomFields" : {
"Invoice.AccountingCustomerParty.Party.Contact.ElectronicMail":"[email protected]",
"Invoice.AccountingCustomerParty.Party.Contact.Name":"Piet Pieters",
"Invoice.AccountingCustomerParty.Party.Contact.Telephone":"015999999",
"Invoice.AccountingSupplierParty.Party.Contact.Telephone":"0385478749",
"Invoice.AccountingSupplierParty.Party.Contact.ElectronicMail": "[email protected]",
"Invoice.AccountingSupplierParty.Party.Contact.Name": "Jean Dupont",
"Invoice.Delivery.DeliveryLocation.ID.Text": "658798574", //in the Delivery segment, goal is give the delivery address a specific identification
"Invoice.AccountingCost":"AccCost95421", //Reference of a Cost center for use by the Receiver
"Invoice.InvoicePeriod.StartDate": "2025-04-01", //To what period the invoice is referring
"Invoice.InvoicePeriod.EndDate": "2025-04-30",
"Invoice.Note": "header note description: additional text information",
"Invoice.ProjectReference.ID.Text": "project number 456854",
"Invoice.ContractDocumentReference.ID.Text": "contract 456999", //A reference to the contract
"PaymentMeansCode": "30",
"PaymentTerms": "30 days end of the month" // PaymentTerms/Note : Free description
},
"Customer": {
"Name": "Billit",
"VATNumber": "BE0563846944",
"PartyType": "Customer",
"Identifiers": [
{
"IdentifierType": "GLN",
"Identifier": "5430003799999"
}
],
"Addresses": [
{
"AddressType": "InvoiceAddress",
"Name": "Billit",
"Street": "Oktrooiplein",
"StreetNumber": "1",
"City": "Ghent",
"Box": "301",
"CountryCode": "BE"
},
]
},
"OrderLines": [
{
"Quantity": 1,
"UnitPriceExcl": 10.0,
"Description": "Box of cookies",
"CustomFields"
:
{
"PeppolUnitCode":"H87",
"PeppolLineID": "40",
"InvoiceLine.Note": "LineNote Extra Free text 1234",
"InvoiceLine.InvoicePeriod.StartDate":"2025-04-01",
"InvoiceLine.InvoicePeriod.EndDate":"2025-04-30"
},
"VATPercentage": 6
},
{
"Quantity": 2,
"UnitPriceExcl": 3.75,
"Description": "Sticks",
"VATPercentage": 21
}
]
}{
"OrderType": "Invoice",
"OrderDirection": "Income",
"OrderNumber": "QS-002",
"OrderDate": "2025-10-06",
"ExpiryDate": "2025-11-30",
"Reference": "8541518799 ", //PO Reference of the buyer
"OrderTitle": "Other Reference 45215487", // Another reference of the buyer
"CustomFields" : {
"Invoice.AccountingCustomerParty.Party.Contact.ElectronicMail":"[email protected]",
"Invoice.AccountingCustomerParty.Party.Contact.Name":"Piet Pieters",
"Invoice.AccountingCustomerParty.Party.Contact.Telephone":"015999999",
"Invoice.AccountingSupplierParty.Party.Contact.Telephone":"0385478749",
"Invoice.AccountingSupplierParty.Party.Contact.ElectronicMail": "[email protected]",
"Invoice.AccountingSupplierParty.Party.Contact.Name": "Jean Dupont",
"Invoice.Delivery.DeliveryLocation.ID.Text": "658798574", //in the Delivery segment, goal is give the delivery address a specific identification
"Invoice.AccountingCost":"AccCost95421", //Reference of a Cost center for use by the Receiver
"Invoice.InvoicePeriod.StartDate": "2025-04-01", //To what period the invoice is referring
"Invoice.InvoicePeriod.EndDate": "2025-04-30",
"Invoice.Note": "header note description: additional text information",
"Invoice.ProjectReference.ID.Text": "project number 456854",
"Invoice.ContractDocumentReference.ID.Text": "contract 456999", //A reference to the contract
"PaymentMeansCode": "30",
"PaymentTerms": "30 days end of the month", // PaymentTerms/Note : Free description
"AdditionalDocumentReference1": "General Conditions Still Apply", //First Document Reference (available on sandbox)
"AdditionalDocumentReference2": "No Commercial Discount", //Second Document Reference (available on sandbox)
"Invoice.OrderReference.SalesOrderID.Text": "TestSalesOrderID", //Reference of the order by the Seller (available on sandbox)
"Invoice.DespatchDocumentReference.ID.Text": "TestDespatchDocumentReference" //Delivery not number (available on sandbox)
},
"Customer": {
"Name": "Billit",
"VATNumber": "BE0563846944",
"PartyType": "Customer",
"Identifiers": [
{
"IdentifierType": "GLN",
"Identifier": "5430003799999"
}
],
"Addresses": [
{
"AddressType": "InvoiceAddress",
"Name": "Billit",
"Street": "Oktrooiplein",
"StreetNumber": "1",
"City": "Ghent",
"Box": "301",
"CountryCode": "BE"
},
]
},
"OrderLines": [
{
"Quantity": 1,
"UnitPriceExcl": 10.0,
"Description": "Box of cookies",
"CustomFields"
:
{ },
"VATPercentage": 6
},
{
"Quantity": 2,
"UnitPriceExcl": 3.75,
"Description": "Sticks",
"VATPercentage": 21
}
]
}{
"OrderType": "Invoice",
"OrderDirection": "Income",
"OrderNumber": "QS-002",
"OrderDate": "2025-05-05",
"ExpiryDate": "2025-06-30",
"CustomFields" : {
"Invoice.TaxRepresentativeParty.PartyName.Name": "TaxRepresentative.Name",
"Invoice.TaxRepresentativeParty.PostalAddress.StreetName": "Oktrooiplein 1",
"Invoice.TaxRepresentativeParty.PostalAddress.PostalZone": "9000",
"Invoice.TaxRepresentativeParty.PostalAddress.CityName": "TaxRepresentative.Address.City",
"Invoice.TaxRepresentativeParty.PostalAddress.Country.IdentificationCode.Text": "BE",
"Invoice.TaxRepresentativeParty.PartyTaxScheme.CompanyID.Text": "BE0400409999",
"Invoice.TaxRepresentativeParty.PartyTaxScheme.TaxScheme.ID.Text": "VAT"
},
"Customer": {
"Name": "Billit",
"VATNumber": "BE0563846944",
"PartyType": "Customer",
"Identifiers": [
{
"IdentifierType": "GLN",
"Identifier": "5430003799999"
}
],
"Addresses": [
{
"AddressType": "InvoiceAddress",
"Name": "Billit",
"Street": "Oktrooiplein",
"StreetNumber": "1",
"City": "Ghent",
"Box": "301",
"CountryCode": "BE"
},
]
},
"OrderLines": [
{
"Quantity": 1,
"UnitPriceExcl": 10.0,
"Description": "Box of cookies",
"VATPercentage": 6
},
{
"Quantity": 2,
"UnitPriceExcl": 3.75,
"Description": "Sticks",
"VATPercentage": 21
}
]
}Updated 3 days ago