Overview

The Invoicing & Payments API lets you send invoice and payment data to Bugalou from external billing systems. This is ideal for service businesses — architects, consultants, freelancers, ZZP'ers — who want to automate payment reminders and track invoice status in one dashboard. You need an API key to authenticate.

Authentication

Include your API key in every request:

• X-API-Key: bg_live_your_key_here
• Authorization: Bearer bg_live_your_key_here

Send Invoice Data

Use the Orders API endpoint with invoice-specific fields:

POST https://app.bugalou.com/api/v1/orders
X-API-Key: bg_live_your_key_here
Content-Type: application/json

{
  "platform": "custom",
  "orderNumber": "INV-2026-042",
  "orderStatus": "processing",
  "customerEmail": "klant@bedrijf.nl",
  "customerName": "Architectenbureau De Groot",
  "items": [
    {"name": "Ontwerp woning - fase 1", "quantity": 1, "price": "2500.00"},
    {"name": "Bouwtechnisch advies", "quantity": 3, "price": "150.00"}
  ],
  "total": "2950.00",
  "currency": "EUR",
  "paymentStatus": "pending",
  "invoiceNumber": "INV-2026-042",
  "invoiceUrl": "https://mijn-boekhouding.nl/facturen/INV-2026-042.pdf"
}

Update Payment Status

When a payment comes in, update the status by sending the same invoice/order number:

POST https://app.bugalou.com/api/v1/orders
X-API-Key: bg_live_your_key_here
Content-Type: application/json

{
  "platform": "custom",
  "orderNumber": "INV-2026-042",
  "orderStatus": "delivered",
  "paymentStatus": "paid",
  "paymentMethod": "bankoverschrijving",
  "amountPaid": "2950.00"
}

The order is upserted — it updates the existing record when orderNumber + platform match.

Invoice Fields Reference

Field	Type	Required	Description
platform	string	Yes	Use "custom" or your billing tool name
orderNumber	string	Yes	Invoice number (e.g. "INV-2026-042")
orderStatus	string	Yes	"processing" (sent), "delivered" (paid), "cancelled"
customerEmail	string	No	Client email address
customerName	string	No	Client or company name
items	JSON array	No	Services/products: [{name, quantity, price}]
total	string	No	Invoice total
currency	string	No	"EUR", "USD", etc.
paymentStatus	string	No	"pending", "paid", "overdue", "refunded"
paymentMethod	string	No	"bankoverschrijving", "iDEAL", "Tikkie"
invoiceNumber	string	No	Invoice reference
invoiceUrl	string	No	Link to invoice PDF
amountPaid	string	No	Amount actually paid

Automation Ideas

• Payment reminder: Trigger a WhatsApp or email when an invoice is overdue
• Payment confirmation: Automatically thank the client when paymentStatus changes to "paid"
• Monthly overview: Use the API to sync invoices and view payment status in one dashboard

Who Is This For?

• Architects and design firms tracking project invoices
• Freelancers and ZZP'ers managing client billing
• Consultants sending payment reminders
• Any service business using tools like Moneybird, Exact, or custom invoicing

Response Format

Success: {"success": true, "order": {...}}

Error: {"error": "Invalid or expired API key"} (401/403)