Invoice Webhook API

With the Webhook API, you can automatically create invoices in your own environment. Once the invoices are created, you can easily send them via email, Peppol or by post.

This functionality allows you to set up a custom integration to send Peppol invoices.

⚠️ Note: This feature is exclusively available for Trilly users.

Request headers

• Authorization: <token>
• X-Company-Id: <your_company_id>

Request body

Invoice

• language: string[2] - 2-letter ISO code for the document language, available options: nl, en, fr, de
• invoice_date: string[10] - invoice date in format YYYY-MM-DD
• expire_days: int - Due date of the invoice, in “days after the invoice date”. Valid values: 0…365
• reference: string[200] (optional) - Extra reference for the invoice, visible in the invoice overview
• intro: text (optional) - Introduction text that appears above the invoice lines on the PDF
• remarks: text (optional) - Footer text below the invoice lines on the PDF
• private_notes: text (optional) - Private text on the invoice, visible to the user but never to the end customer
• vat_shifted: int (optional) - Is reverse charge VAT applicable to the invoice. Note: all lines must use vat_percentage=0 if this field has a value other than 0. Available values:
  • 0: No (= default)
  • 2: Co-contractor
  • 4: Intra-community services
  • 8: Intra-community goods
  • 32: Margin scheme
  • 64: Import export
  • 128: Outside EU
• client: client - The client that should be linked to the invoice
• lines: array<invoice_line> - List of invoice lines to be linked to the invoice

Client

• company_type: string - Available values: “bedrijf”, “particulier”
• type: string - if company_type=bedrijf --> Legal form of the company. Available values: onbekend, bvba, bv, eenmanszaak, nv, sbvba, ebvba, cvba, cvba-vso, cvoa, cvoa-vso, vof, gcv, comm.v, comm.va, esv, lv, vzw, vvzrl, tv, natuurlijk-persoon, limited-ltd, limited-llc, incorporated, srl, scri, sa, sas, sarl, sarl-s, gmbh, ag, srl, spa, doo, sl, sc, asbl, vme, feitelijke-vereniging
• title: string[255] - The company name if company_type=bedrijf. Not required if particulier
• email: string[150]
  • vat_country_code: string[2] - 2-letter ISO country code for the VAT number, e.g. ‘BE’
• vat_id: string[30] - Additional values of the VAT number, e.g. “0663.642.920”
• first_name: string[255], required if company_type=particulier
• last_name: string[255], required if company_type=particulier
• address: string[200], billing address (street + number)
• address_zip: string[12] postal code of the billing address
• address_city: string[150] city/location of the billing address
• address_country: string[2] 2-letter ISO code of the billing address country
• telephone: string[100] - optional

Invoice line

• description: text - Text for the invoice line
• unit_price: double - Unit price per item
• amount: double - Number of items
• vat_percentage: double - e.g. 21.00

Example request payload

[
  {
    "language": "nl",
    "invoice_date": "2025-01-10",
    "expire_days": 14,
    "reference": "Webshop #111",
    "intro": "",
    "remarks": "",
    "private_notes": "Webshop #111",
    "vat_shifted": 0,
    "client": {
      "company_type": "bedrijf",
      "type": "onbekend",
      "title": "TestCompany",
      "email": "info@numnum.be",
      "vat_country_code": null,
      "vat_id": null,
      "first_name": "Wim",
      "last_name": "De Bakker",
      "address": "Markt 1",
      "address_zip": "8000",
      "address_city": "Brugge",
      "address_country": "BE",
      "telephone": ""
    },
    "invoice_lines": [
      {
        "description": "Line 1",
        "unit_price": 10.00,
        "amount": 2.5,
        "vat_percentage": 21.00
      },
      {
        "description": "Line 2",
        "unit_price": 20.00,
        "amount": 5,
        "vat_percentage": 21.00
      },
      {
        "description": "Shipping",
        "unit_price": 20.00,
        "amount": 5,
        "vat_percentage": 21.00
      }
    ]
  }
]

Result

The API will return HTTP 201 if the resource was successfully created; treat all other status codes (200, 403, 500, …) as a failure and place the invoice in a queue for retry later.

HTTP 201 - Invoice created

Returns a list of IDs of the created invoice(s)

[10232,10233]

HTTP 403 - Forbidden

Problem with validation of the Authorization token in the request header

{exception: "Information..."}

HTTP 406 - Failed, validation problem

Returned when there is a problem with the payload validation

{exception: "Information..."}

HTTP 500 - Unexpected problem

HTTP 200 - Unexpected problem

Regular HTTP code. However, this should be treated as “retry” because the API only returns HTTP 201 upon actual creation

Postman

📥 Download via this link a Postman example of the webhook.