Sage Cloud Demat Invoicing
Start
EN

Create invoices via the API

This endpoint creates sales invoices in Sage Cloud Demat Invoicing. Once created, you can send them by email, Peppol or post.

ℹ️ Authentication (personal API token + X-Company-Id), limits and general error codes are in the Developer API overview. Read that first.

Endpoint

POST https://www.clouddematinvoicing.be/api/v1/webhooks/create-invoice

Headers:

Authorization: Bearer <your-api-token>
X-Company-Id: <your-company-id>
Content-Type: application/json
Accept: application/json

Request body

The body is a JSON array of invoice objects. You can create one or more invoices at once (max 50, processed atomically).

Invoice fields

Field Type Required Description
language string Yes Invoice language (sets the PDF language): nl, fr, en or de
invoice_date string Yes Invoice date in YYYY-MM-DD format (e.g. 2026-02-15)
expire_days integer Yes Number of days after the invoice date until the due date (0–365)
reference string No Your own reference (e.g. order number), max 255 chars
intro string No Intro text above the invoice lines, max 255 chars
remarks string No Remark below the invoice lines (visible to the customer), max 255 chars
private_notes string No Private note (internal only, not on the PDF), max 255 chars
payment_info string No Payment info display: yes (default), no or paid (see below)
vat_shifted integer No VAT reverse-charge regime (see table below). Default 0
client object Yes Customer details (see Client object)
invoice_lines array Yes At least 1 invoice line (see Invoice lines)

payment_info

Value Behaviour
yes Show payment information on the invoice (default)
no Hide payment information
paid Mark the invoice as paid immediately; a payment is automatically registered for the full amount

vat_shifted

VAT reverse-charge regime:

Value Meaning
0 No VAT shift (default)
1 VAT shifted (general)
2 Co-contractor (works on immovable property)
4 Intra-Community supply of services (B2B)
8 Intra-Community supply of goods (B2B)
32 VAT margin scheme
64 Export of goods (outside EU)
128 Services rendered outside EU (B2B)

⚠️ For any value other than 0, all invoice lines must have vat_percentage: 0. The customer usually needs a valid VAT number (e.g. for intra-Community supplies).

Client object

Field Type Required Description
company_type string Yes company or individual (legacy: bedrijf / particulier)
type string If company Legal form (e.g. bv, nv, vzw). See Entity types
email string Yes Valid email address, max 255 chars
first_name string Yes Contact first name
last_name string Yes Contact last name
address string Yes Street + number
address_zip string Yes Postal code
address_city string Yes City
address_country string Yes Country code, exactly 2 letters (ISO 3166-1, e.g. BE)
vat_country_code string No VAT country code, exactly 2 letters (e.g. BE)
vat_id string No VAT number without country code (e.g. 0123456789). Dots/spaces are normalized
title string No Salutation, max 255 chars
telephone string No Phone number, max 255 chars

ℹ️ The type field is only required for companies (company / bedrijf), not for individuals.

Invoice lines (invoice_lines)

Field Type Required Description
description string Yes Product or service description, max 255 chars
unit_price numeric Yes Unit price excluding VAT (dot as decimal separator, e.g. 99.99)
amount numeric Yes Number of units (may be decimal, e.g. 2.5)
vat_percentage numeric Yes VAT percentage without % (e.g. 21, 6, 0)

Totals are calculated automatically:

  • net = unit_price × amount
  • vat = net × (vat_percentage / 100)
  • total = net + vat

Example: invoice for a company

curl -X POST https://www.clouddematinvoicing.be/api/v1/webhooks/create-invoice \
  -H "Authorization: Bearer <your-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "en",
      "invoice_date": "2026-02-15",
      "expire_days": 30,
      "reference": "ORDER-2026-001",
      "intro": "Thank you for your order!",
      "remarks": "Please pay within 30 days.",
      "payment_info": "yes",
      "vat_shifted": 0,
      "client": {
        "company_type": "company",
        "type": "bv",
        "email": "info@customer.be",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "first_name": "Jan",
        "last_name": "Janssen",
        "address": "Kerkstraat 1",
        "address_zip": "1000",
        "address_city": "Brussels",
        "address_country": "BE",
        "telephone": "+32 2 123 45 67"
      },
      "invoice_lines": [
        { "description": "Website development", "unit_price": 1500.00, "amount": 1, "vat_percentage": 21 },
        { "description": "Hosting (12 months)", "unit_price": 15.00, "amount": 12, "vat_percentage": 21 }
      ]
    }
  ]'

Example: individual customer

For an individual, type and vat_id are not required:

[
  {
    "language": "en",
    "invoice_date": "2026-02-20",
    "expire_days": 14,
    "client": {
      "company_type": "individual",
      "email": "john.doe@gmail.com",
      "first_name": "John",
      "last_name": "Doe",
      "address": "Dorpstraat 45",
      "address_zip": "9000",
      "address_city": "Ghent",
      "address_country": "BE"
    },
    "invoice_lines": [
      { "description": "Logo graphic design", "unit_price": 350.00, "amount": 1, "vat_percentage": 21 }
    ]
  }
]

Example: VAT reverse charge (intra-Community)

For reverse charge, use vat_shifted and vat_percentage: 0:

[
  {
    "language": "en",
    "invoice_date": "2026-02-25",
    "expire_days": 30,
    "vat_shifted": 4,
    "remarks": "Reverse charge - VAT to be accounted for by the customer",
    "client": {
      "company_type": "company",
      "type": "gmbh",
      "email": "info@deutschefirma.de",
      "vat_country_code": "DE",
      "vat_id": "123456789",
      "first_name": "Hans",
      "last_name": "Müller",
      "address": "Hauptstraße 10",
      "address_zip": "10115",
      "address_city": "Berlin",
      "address_country": "DE"
    },
    "invoice_lines": [
      { "description": "Consulting services", "unit_price": 2500.00, "amount": 1, "vat_percentage": 0 }
    ]
  }
]

Response

HTTP 201: Created

{
  "invoices": [1234, 5678]
}

invoices is a list of internal database IDs in the same order as the input; these are not invoice numbers. Invoice numbers are generated automatically according to your company settings.

Errors

See the error table in the API overview. A validation error looks like this:

{
  "error": "invalid_body",
  "errors": {
    "0.language": ["The language must be one of: nl, fr, en, de."],
    "0.client.email": ["The client email must be a valid email address."],
    "0.invoice_lines.0.unit_price": ["The unit price must be a number."]
  }
}

Client matching (avoiding duplicate clients)

For each invoice, Sage Cloud Demat Invoicing checks whether the client already exists, otherwise it creates one:

  • With a VAT number (vat_country_code + vat_id): match on your company + the normalized VAT number. Formatting doesn’t matter: 0123456789 and 0123.456.789 match the same client.
  • Without a VAT number: fall back to the combination company + vat_id + email. Use a consistent email address to avoid duplicates.

⚠️ If the client already exists (VAT match), it is not overwritten with the new details (name, address, email). Change client details in Sage Cloud Demat Invoicing itself.

Notes

  • Amounts: use a dot as the decimal separator (1234.56), no comma and no thousands separator.
  • Dates: YYYY-MM-DD format with leading zeros (2026-02-05).
  • VAT: numeric value without a % sign (21, not "21%" or 0.21).
  • Atomic: if one invoice in the batch fails, none are created.
  • Automatic numbering: you cannot supply your own invoice number.

Entity types

Valid values for client.type (only required for companies), among others: bv, nv, vzw, bvba, cvba, comm.v, comm.va, vof, eenmanszaak, sa, sarl, sas, srl, gmbh, ag, limited-ltd, limited-llc, natuurlijk-persoon, onbekend. Not sure? Use onbekend.

Deprecated endpoint

The old endpoint POST /webhooks/create-invoice (without /api/v1) still works for existing integrations but is deprecated: it returns a bare list ([10232, 10233]) and uses different error codes (406/401). Migrate to POST /api/v1/webhooks/create-invoice.