Extra Fields : How can I Extend Content with Extra Values

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, currently available on Sandbox only.

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, currently available on Sandbox only.

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, currently available on Sandbox only.

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, currently available on Sandbox only.

Popular examples include

GTIN - Ean number (SRV)
PO number (PO)
Part number (BH)
Batch Number (NB)
Serial Number (SN)

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, currently available on Sandbox only.

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
   }
 ]
}