API Documentation
API Documentation
Start typing to search…

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 JsonResult in Peppol UBLResult on Billit generated Human Readable
Invoice.NoteHeader - Custom FieldsNoteNot displayed on PDF
CommentsHeaderNoteWill 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 PeppolExtra Information
Invoice.TaxPointDateTaxPointDateMention date if if the VAT tax point date is different from the Invoice issue date
Invoice.InvoicePeriod.StartDateInvoicePeriodStart date of the services (header level)
Invoice.InvoicePeriod.EndDateInvoicePeriodEnd date of the services (header level)
Invoice.ContractDocumentReference.ID.TextContractDocRefContract number
Invoice.ProjectReference.ID.TextProjectReferenceProject Identification
Invoice.AccountingCostAccountingCostInfo 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.
PaymentTermsPaymentTerms/NoteAdditional free text description for Payment Terms. Here you can add various payment terms descriptions
PaymentMeansCodePaymentMeansCodeBillit 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.TextSalesOrderIDSales order number (Number of the order registered by the Seller)
Invoice.DespatchDocumentReference.ID.TextDespatchDocRefNumber of the Delivery Note
AdditionalDocumentReferenceAdditionalDocumentReferenceAdd one or more document references, this is free additional information on header level, more info in separate segment below

Additional Document Reference (Header)

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.

Examples Below with additional document references in custom field. In the Peppol UBL, no DocumentTypeCode is included.

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

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.

ValueLinked 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

Json Example:

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

Not operational:

Invoice.TaxRepresentativeParty.PartyTaxScheme.CompanyID (Text)
Invoice.TaxRepresentativeParty.PartyTaxScheme.TaxScheme.ID

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

Updated 20 days ago