Extra Fields : Extend Content (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 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

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",

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, 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	DocumentReference	Add one or more document references, this is free additional information on header level, one line per information element.

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.ID.SchemeID	Link	A structured value, for GLN number this is 0088
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

Exemples of Delivery location below (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)
    },

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

https://docs.billit.be/docs/create-first-invoice.

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"
    :
    {
               "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
   }
 ]
}