API Documentation

Extra Fields : How can I Extend Content with Extra Values

Custom Fields - Extra Fields - More 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 with other requirement then Peppol.

You can add these fields for both Invoices and Creditnote. To avoid mistakes, the root element (Invoice, CreditNote, InvoiceLine,CreditNoteLine) must always be declared.

The allowed values for Income can be found in the lists below.

Order (Header Level - Income)

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.AccountingCustomerParty.Party. PartyIdentification.ID.TextAccountingCustPartyParty identification is one of the optional identifications
Invoice.InvoicePeriod.StartDateLinkStart date of the services (header level)
Invoice.InvoicePeriod.EndDateLinkEnd date of the services (header level)
Invoice.ContractDocumentReference.ID.TextContractDocumentRefContract number
Invoice.ProjectReference.ID.TextProjectReferenceProject Identification
Invoice.AccountingCostLinkInfo for the Buyer about how to put in the Accounts (CostID, GL, other reference on request of buyer)
PaymentTermsLinkAdditional text description for Payment Terms
Invoice.NoteLinkFree text on header level for comments
PaymentMeansCodeLinkBillit will automatically generate a payment means code. But if a specific code is required, it can be set.

Order : Delivery Location (Header Level - Income)

It can be important the specify where goods are delivered. Below more information.

Key (Header)Linked Info When PeppolExtra Information
Invoice.Delivery.DeliveryLocation.ID.TextLinkA number of reference for the delivery location
Invoice.Delivery.DeliveryLocation.PostalAddress. StreetNameLink
Invoice.Delivery.DeliveryLocation.PostalAddress. AdditionalStreetNameLink
Invoice.Delivery.DeliveryLocation.PostalAddress. CityNameLink
Invoice.Delivery.DeliveryLocation.PostalAddress. PostalZoneLink
Invoice.Delivery.DeliveryLocation.PostalAddress. CountrySubentityLink
Invoice.Delivery.DeliveryLocation.PostalAddress. Country. IdentificationCode.TextLink

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.NameLink
Invoice.AccountingSupplierParty.Party.Contact.TelephoneLink
Invoice.AccountingSupplierParty.Party.Contact.ElectronicMailLink
Invoice.AccountingCustomerParty.Party.Contact.NameLink
Invoice.AccountingCustomerParty.Party.Contact.TelephoneLink
Invoice.AccountingCustomerParty.Party.Contact.ElectronicMailLink

Orderline (Line level - Income)

Key (Line)Linked Info When Peppol
PeppolUnitCodeLink .Unit of Measure. Code list. Sample value H87
InvoiceLine.InvoicePeriod.StartDateLinkStart date of the services (Line level)
InvoiceLine.InvoicePeriod.EndDateLinkEnd date of the services (Line level)
InvoiceLine.Item.CommodityClassification.ItemClassificationCode.TextLinkThe description text.
InvoiceLine.Item.CommodityClassification.ItemClassificationCode.ListIDLinkThis ID must be compliant with the code list.
PeppolLineIDLinkThe line number is autogenerated by Billit. With PeppolLineID, you can set your own values.
InvoiceLine.NoteLinkExtra free text for additional info

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

Will be supported in the future

Key (Header)Value (TransferType = Peppol)
Invoice.OrderReference.SalesOrderID.ID.Texthttps://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/cac-OrderReference/cbc-SalesOrderID/