Self-billing (purchase borderelle) via the API

These endpoints create issued purchase borderelles, known in Belgian VAT terms as self-billed invoices. This is a document your company draws up on behalf of a supplier (e.g. a milk-money settlement a dairy company issues for a dairy farmer).

Typical users: producers and cooperatives that periodically create settlements for their suppliers, or external systems that generate settlements and want to submit them to NumNum while keeping their own PDF layout.

ℹ️ Authentication (personal API token + X-Company-Id), limits and general error codes are in the Developer API overview. The headers and client matching are identical to the Invoice API.

Endpoints

POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle
POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote

Request body: purchase borderelle

A JSON array of borderelles (processed atomically). The structure resembles the Invoice API, with a few differences.

Lines (lines)

"lines": [
  { "description": "Milk delivery 1–15 May (litre)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 }
]

Same fields as an invoice line: description, unit_price, amount, vat_percentage. amount may be decimal (e.g. litre/kg). Totals are calculated server-side.

Supplier IBAN and BIC

The supplier’s IBAN is required to send the borderelle via Peppol: a purchase borderelle is a self-billing document, and the Peppol UBL must contain the supplier’s account (rule BR-61). Without an IBAN the document is still created, but NumNum refuses to send it via Peppol. So include iban (and preferably bic) in the client object.

Both notations are valid and give the same result:

"client": { "iban_country_code": "BE", "iban": "82103021737768", "bic": "GKCCBEBB" }

"client": { "iban": "BE82 1030 2173 7768", "bic": "GKCCBEBB" }

• Spaces, dots and dashes are allowed; they are stripped.
• If you send both iban_country_code and an iban that already starts with a country code, the two must match. If they conflict (e.g. NL with BE82…), you get 400 invalid_body.
• An invalid IBAN or BIC format also returns 400 invalid_body; the whole batch is then rejected.
• If the supplier already exists and already has an IBAN, it stays unchanged: existing bank details are never overwritten by the API. Empty fields are filled in.
• Forgot it? You can add the IBAN afterwards on the supplier record under Financial details (see Self-billing: how does it work?).

Attaching your own PDF (attachment_pdf)

Want to keep your own PDF layout? Send a base64-encoded PDF. It is stored as an attachment on the document and included in Peppol delivery. NumNum still generates a standard PDF from the document data as well.

• Max size ± 15 MB (base64). Stay well below this.
• If attachment_pdf_filename is missing, <borderelle-nr>.pdf is used.
• Send only real PDFs; the content type is forced to application/pdf.

// Node.js
const fs = require('fs')
const pdfBase64 = fs.readFileSync('./milk-money-may-2026.pdf').toString('base64')

Request body: credit note

Almost identical to a borderelle, with these differences:

All other fields behave identically. Use negative or corrective amounts depending on your correction.

Example: milk-money settlement

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle \
  -H "Authorization: Bearer <your-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "en",
      "purchase_borderelle_date": "2026-05-20",
      "expire_days": 30,
      "reference": "Milk money May 2026",
      "payment_info": "no",
      "client": {
        "company_type": "company",
        "type": "onbekend",
        "email": "farmer@example.be",
        "first_name": "Jan",
        "last_name": "De Boer",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "address": "Boerderijstraat 1",
        "address_zip": "9800",
        "address_city": "Deinze",
        "address_country": "BE",
        "iban_country_code": "BE",
        "iban": "82103021737768",
        "bic": "GKCCBEBB"
      },
      "lines": [
        { "description": "Milk delivery 1–15 May (litre)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 },
        { "description": "Milk delivery 16–31 May (litre)", "unit_price": 0.46, "amount": 13200, "vat_percentage": 6 }
      ]
    }
  ]'

Example: credit note on a borderelle

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote \
  -H "Authorization: Bearer <your-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "language": "en",
      "purchase_borderelle_creditnote_date": "2026-05-21",
      "purchase_borderelle_uuid": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "reference": "Correction milk money May",
      "client": { "company_type": "company", "type": "onbekend", "email": "farmer@example.be", "first_name": "Jan", "last_name": "De Boer", "vat_country_code": "BE", "vat_id": "0123456789", "address": "Boerderijstraat 1", "address_zip": "9800", "address_city": "Deinze", "address_country": "BE", "iban_country_code": "BE", "iban": "82103021737768", "bic": "GKCCBEBB" },
      "lines": [
        { "description": "Correction quality premium", "unit_price": -50.00, "amount": 1, "vat_percentage": 6 }
      ]
    }
  ]'

Response

HTTP 201: Created

Purchase borderelle:

{ "purchase_borderelles": [1234, 1235] }

Credit note:

{ "purchase_borderelle_creditnotes": [987] }

The array contains the internal database IDs in the same order as the input.

Errors

See the error table in the API overview. Validation errors follow the same invalid_body format as the Invoice API, indexed by position (0.client.email, 1.lines.0.unit_price, …). A purchase_borderelle_uuid from another company returns 404.

Difference from the Invoice API

Notes

• Numbering: the borderelle number is generated automatically (typically with an AB prefix). You cannot supply your own number.
• Not idempotent: sending the same payload twice creates two documents.
• Peppol requires an IBAN: without client.iban the borderelle is created but not sent via Peppol. See Bank details.
• Received purchase borderelles (from a supplier) come in via Peppol; that is not a use case for this API.