Extra Fields : How can I Extend Content with Extra Values
Custom Fields - Extra Fields - More Fields
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 of of both : use Invoice.Note or Comments, NOT both
- Billit Human Readable will only be generated if you did not include your own PDF
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.AccountingCustomerParty.Party. PartyIdentification.ID.Text | AccountingCustParty | Party identification is one of the optional identifications | 
| 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, GL, other reference on request of buyer) | 
| 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 (*1) | SalesOrderID | Sales order number (Number of the order registered by the Seller) | 
| Invoice.DespatchDocumentReference.ID.Text (*1) | DespatchDocRef | Number of the Delivery Note | 
| AdditionalDocumentReference (*1) | DocumentReference | Add one or more document references, this is free additional information on header level, one line per information element. | 
(*1) : New, available on Sandbox and Production.
Order : Delivery Location (Header Level - Income)
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.PostalAddress. StreetName | Link | Street delivery location | 
| Invoice.Delivery.DeliveryLocation.PostalAddress. AdditionalStreetName | Link | Second streed field | 
| Invoice.Delivery.DeliveryLocation.PostalAddress. CityName | Link | Delivery City | 
| Invoice.Delivery.DeliveryLocation.PostalAddress. PostalZone | Link | Delivery Zip | 
| Invoice.Delivery.DeliveryLocation.PostalAddress. CountrySubentity | Link | Delivery country sub entity (e.g. province) | 
| Invoice.Delivery.DeliveryLocation.PostalAddress. Country. IdentificationCode.Text | Link | Delivery Country code (e.g. BE, FR, NL | 
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, it can also be included in the fields below.
| 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 | 
Orderline (Line level - Income)
Include in section "Custom Fields" in the Orderline part.
| Key (Line) | Linked Info When Peppol | Description | 
|---|---|---|
| PeppolUnitCode | Link . | Unit of Measure. Code list. Sample value H87 | 
| InvoiceLine.InvoicePeriod.StartDate | Link | Start date of the services (Line level) | 
| InvoiceLine.InvoicePeriod.EndDate | Link | End date of the services (Line level) | 
| PeppolLineID | Link | The line number is autogenerated by Billit. With PeppolLineID, you can set your own value. | 
| InvoiceLine.Note | Link | Extra free text for additional info on line. You can put multiple information elements in one Note segment. | 
| InvoiceLine.OrderLineReference.LineID (*1) | OrderLineRef | Link to the line of the order of the buyer. | 
(*1) : New, available on Sandbox and Production.
Orderline (Line level - Income) - Article Information
| Key (Line) | Linked Info When Peppol | Description | 
|---|---|---|
| InvoiceLine.Item.BuyersItemIdentification.ID.Text (*) | Link | ArticleNumber as stored by the buyer of your article | 
| InvoiceLine.Item.StandardItemIdentification.ID.Text (*) | Link | This is the article number according to one of the standardisation types (see next point) | 
| "InvoiceLine.Item.StandardItemIdentification.ID.SchemeID": "0160" (*) | Link | The standardisation scheme ID, example 0160. | 
(*1) : New, available on Sandbox and Production.
Example Json below with with standardised article number based on GTIN:
"InvoiceLine.Item.StandardItemIdentification.ID.Text": "8710400311140", "InvoiceLine.Item.StandardItemIdentification.ID.SchemeID": "0160"
Example Json below with with Buyersitemidentification:
"InvoiceLine.Item.BuyersItemIdentification.ID.Text": "854565"
Orderline (Line level - Income) - Commodity Classification
CommodityClassification:
- Allows to include a value linked to a standard/structered ID. This ID gives the meaning.
- The ID must be in the list of the allowed values : codelist
- Multiple lines with information can be inserted
| Key (Line) | Linked Info When Peppol | Description | 
|---|---|---|
| CommodityClassificationID (*1) | Commodity | ID and value of the CommodityClassification. | 
(*1) : New, available on Sandbox and Production.
Popular examples include
Example Json below with PO number and GTIN:
"CommodityClassificationPO": "45123456789", "CommodityClassificationSRV": "5410355405132"
Orderline (Line level - Income) - AdditionalItemProperty
AdditionalItemProperty:
- Allows to include a value linked to a field description (free choice) .
- Multiple lines with information can be inserted
- When to use ? When there is no structured Peppol field available, and you do not use Note, then this is the best option.
| Key (Line) | Linked Info When Peppol | Description | 
|---|---|---|
| AdditionalItemPropertyXYZ (*1) | Commodity | ID and value of the CommodityClassification. | 
(*1) : New, available on Sandbox and Production.
Popular examples include
- Other product descriptions
- Intrastat code
- Weight
- Dimensions
- Any other additional information
Example Json below with Weight and Intrastat code:
"AdditionalItemPropertyWeight": "24 kg", "AdditionalItemPropertyIntrastatCode": "4527897"
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 | 
| Invoice.TaxRepresentativeParty.PartyTaxScheme.CompanyID (Text) | Link | 
| Invoice.TaxRepresentativeParty.PartyTaxScheme.TaxScheme.ID | (Link | 
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"
    :
    {
               "InvoiceLine.Item.CommodityClassification.ItemClassificationCode.Text":"45123456789",
               "InvoiceLine.Item.CommodityClassification.ItemClassificationCode.ListID":"PO",         
               "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"
    :
    {
               "PeppolUnitCode":"H87", //If you want to set a specific UOM (Unit Of Measure)
               "PeppolLineID": "40",  //Number of the line of the invoice
               "InvoiceLine.Note": "LineNote Extra Free text 1234",  // free text
               "InvoiceLine.InvoicePeriod.StartDate":"2025-04-01", 
               "InvoiceLine.InvoicePeriod.EndDate":"2025-04-30",
               "InvoiceLine.OrderLineReference.LineID": "0010",  //Reference to the Line of the order of the buyer
               "AdditionalItemPropertyWeight": "24 kg",  //AdditionalItemProperty 1
     					 "AdditionalItemPropertyIntrastatCode": "4527897"  //AdditionalItemProperty2
      "InvoiceLine.Item.BuyersItemIdentification.ID.Text": "854565",
 "InvoiceLine.Item.StandardItemIdentification.ID.Text": "8710400311140", // GTIN number
              "InvoiceLine.Item.StandardItemIdentification.ID.SchemeID": "0160" // scheme ID indicating it is a GTIN number
        },
   "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 about 3 hours ago