API Documentation

Creating your first invoice

AhnHa this easy?

Creating the first invoice is that illuminating moment when you think, "Aha! This is how it works!" Understanding the significance of this experience, we've streamlined the process to make it as straightforward as possible.

No need for multiple calls to create the invoice or additional development to accommodate various e-invoice networks. Everything is consolidated into one simple endpoint.

As you will see in the example there is no need to first create the customer and then the invoice. We will try and find an existing customer based on VAT, Email, Address, CustomerNr if enabled. if not we will auto create a new one for you saving the hassle for the extra API Call.

Link to Postman collection -> (Create First Invoice)

When the Postman or the information below is successfully implemented you can start creating invoices as much as you want. No limits! Running Bulk invoice runs or continuous runs this is how you handle it!

Detailed information

Below you can find the Endpoint used and the JSON for creating a basic invoice. By executing this request you will receive a Unique ID. This ID indicates success together with the 200 response code, we advice storing the Unique ID onto your own invoice Object or references to this invoice.

As you will see no calculations will have to be done by you. We will always calculate the data provided by you. More information on calculations can be found here

In this test Example no PDF or other attachments have been added. If you would like to add these because you have your own PDFs or you would just like to add an other attachment follow this extra Step! If you provide no invoice PDF Billit will generate one for you with the data provided into the API Call.

The example below will create a Sales invoice this can be seen by the following properties.

PropertyValueInfo
OrderTypeInvoiceIndicating the invoice type. "Invoice", "CreditNote",...
OrderDirectionIncomeIndicating the direction for the company. "Income", "Cost"

The Metadata of the invoice is stored in the following properties.

PropertyValueInfo
OrderNumberQS-001Invoice number, Unique invoice identifier,....
OrderDate2024-01-01The issue date of the invoice
ExpiryDate2024-01-31The date where the invoice is overdue for the end recipient
CustomerObjectCustomer information
OrderlinesListThe products, invoiceable items, ....

Customer Object

PropertyValueInfo
NameBillitCommercial Name, DisplayName, ...
VATNumberBE0563846944Taxnumber for the company
PartyTypeCustomerCustomer for Sales invoices, Supplier for Purchase invoices
IdentifiersObjectList of idenitifiers for the customer outside of the Unique Taxnumber
AddressesListList of addresse for the customer

OrderLines Object

PropertyValueInfo
Quantity1The amount to quantify with
UnitPriceExcl10.0The NET price of the line
DescriptionBox of cookiesThe title of the line
VATPercentage6.0Percentage of tax to be added on the line

API Request

📘

Testable request in Postman: 01 - Create Sales Invoice

EndpointMethodResponse
/v1/ordersPostINT (Unique OrderID)
{
 "OrderType": "Invoice",
 "OrderDirection": "Income",
 "OrderNumber": "QS-001",
 "OrderDate": "2024-01-01",
 "ExpiryDate": "2024-01-31",
  "Customer": {
   "Name": "Billit",
   "VATNumber": "BE0563846944",
   "PartyType": "Customer",
   "Identifiers": [
        {
        "IdentifierType": "GLN",
        "Identifier": "5430003732007"
        }
    ],
   "Addresses": [
        {
        "AddressType": "InvoiceAddress",
        "Name": "Billit",
        "Street": "Oktrooiplein",
        "StreetNumber": "1",
        "City": "Ghent",
        "Box": "301",
        "CountryCode": "BE"
        },
        {
        "AddressType": "DeliveryAddress", //The delivery address, if not provided will be automatically the same as invoice address
        "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
   }
 ]
}

Validations

📘

Testable request in Postman: 02 - Validation Example

We will validate your data before processing it into Billit. Therefor you could potentially run into one of these while building. A response can look like the following for example when using a wrong VAT percentage for the country you are invoicing from.

{
    "errors": [
        {
            "Code": "InvalidVAtPercentageForTaxCountry_0_",
            "Description": "Invalid VAT percentage for country code BE"
        }
    ]
}