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

payment_info

vat_shifted

VAT reverse-charge regime:

⚠️ 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

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

ℹ️ Bank details are optional. If you send both iban_country_code and an iban that already starts with a country code, the two must match; otherwise you get 400 invalid_body. If the client already exists and already has an IBAN, it is never overwritten; empty fields are filled in.

Invoice lines (invoice_lines)

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.