REST API v1
Create clients and invoices, issue and send them, record payments and read reports. JSON over HTTPS. Base URL: https://flowzeen.com/api/v1
Authentication
Create a key under Settings → Developer. Send it as a bearer token. Keys belong to one organization, carry scopes, and are stored only as hashes: the key is shown once at creation. Rotate keys regularly; revoked keys stop working immediately.
Authorization: Bearer fz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| Scope | Grants |
|---|---|
| invoices:read / invoices:write | List, read, create, edit drafts, issue, send, record payments, cancel |
| clients:read / clients:write | List, read, create, update, archive clients |
| quotes:read / quotes:write | List, read, create, update, send quotes; convert accepted quotes |
| reports:read | Revenue report |
Conventions
Money is always a decimal string ("1234.50"), rounded to the currency's minor unit. Send amounts as strings or numbers; all calculations happen on the server. Totals you send are ignored.
Dates are YYYY-MM-DD; timestamps are UTC ISO-8601.
Pagination: ?page=1&per_page=25 (max 100). Responses contain meta.total and meta.total_pages. Sorting: ?sort=amount&dir=asc. Filtering: e.g. ?status=paid&client_id=3&q=acme&from=2026-01-01&to=2026-03-31.
Idempotency: send Idempotency-Key: <8–120 chars> on POST requests. A retry with the same key and body returns the original response (header Idempotent-Replayed: true); the same key with a different body returns 422 idempotency_mismatch.
Rate limits: 120 requests per minute per key. Headers X-RateLimit-Limit and X-RateLimit-Remaining; 429 responses include Retry-After.
Status codes: 200 OK · 201 Created · 400 bad JSON · 401 missing/invalid key · 403 missing scope · 404 not found (also for other organizations' ids) · 409 state conflict · 422 validation · 429 rate limited · 502 email transport failure · 500 server error.
{
"error": {
"code": "validation_failed",
"message": "The request contains invalid data.",
"fields": { "items.0.description": "Description is required." }
}
}Clients
curl -X POST https://flowzeen.com/api/v1/clients \
-H "Authorization: Bearer $FLOWZEEN_KEY" -H "Content-Type: application/json" \
-d '{"company_name":"Northwind GmbH","email":"anna@northwind.test","country_code":"AT","currency":"EUR","payment_terms_days":14}'{ "data": { "id": 12, "company_name": "Northwind GmbH", "email": "anna@northwind.test", "country_code": "AT", "currency": "EUR", ... } }GET /clients (filters: q, archived=1; create with client_type = company (needs company_name) or private (needs first_name + last_name); sort: company_name|created|email) · GET /clients/{id} (adds a per-currency summary) · PATCH /clients/{id}
Invoices
curl -X POST https://flowzeen.com/api/v1/invoices \
-H "Authorization: Bearer $FLOWZEEN_KEY" -H "Idempotency-Key: order-1042" -H "Content-Type: application/json" \
-d '{
"client_id": 12,
"currency": "EUR",
"issue_date": "2026-03-01",
"items": [
{"description":"Consulting","quantity":"10","unit_price":"100.00","tax_rate":"20"},
{"description":"Licence","quantity":"1","unit_price":"99.99","tax_rate":"10","discount_type":"percent","discount_value":"10"}
],
"discount_type": "fixed", "discount_value": "5.00",
"notes": "Thank you!"
}'{ "data": { "id": 57, "number": null, "status": "draft", "currency": "EUR", "subtotal": "1089.99", "discount_total": "5.00",
"net_total": "1084.99", "tax_total": "208.12", "gross_total": "1293.11", "balance_due": "1293.11", "items": [ ... ] } }POST https://flowzeen.com/api/v1/invoices/57/issue # assigns the permanent number, locks the invoice
POST https://flowzeen.com/api/v1/invoices/57/send # {"to":"anna@northwind.test","message":"…"} — PDF attached
POST https://flowzeen.com/api/v1/invoices/57/payments # {"amount":"500.00","paid_on":"2026-03-10","method":"bank_transfer","reference":"TX-1"}{ "data": { "status": "accepted", "to": "anna@northwind.test", "note": "Accepted by the mail server. Delivery is not confirmed." } }Invoice states: draft → issued → sent → viewed → partially_paid → paid, plus overdue and cancelled. Status is derived by the server from facts (payments, due date, sent/viewed events); it cannot be set directly. Only drafts are editable; issued invoices return 409 on PATCH. Overpayments are rejected.
GET /invoices (filters: status, client_id, q, from, to, currency; sort: number|issue_date|due_date|amount|status|created) · GET /invoices/{id} (with items, payments, events) · PATCH /invoices/{id} · DELETE /invoices/{id} (drafts only) · POST /invoices/{id}/duplicate|cancel|remind · DELETE /invoices/{id}/payments/{paymentId} (void) · POST /invoices/{id}/public-link
Integrations: external references and change polling
Clients, products, invoices, quotes and recurring profiles accept an optional external_ref (up to 120 characters: letters, digits and : _ - . / @), for example woo:3fa9c1de:order:1042. List endpoints for clients, products and invoices can filter with ?external_ref=… and ?updated_since=2026-01-31T12:00:00Z (ISO 8601). Webhook payloads for invoice.* and payment.recorded include the invoice's external_ref. Together with Idempotency-Key this lets a connector sync without ever creating duplicates. The official WooCommerce plugin lives in integrations/wordpress.
Products
GET|POST /products · GET|PATCH|DELETE /products/{id} (scopes products:read / products:write). Fields: name, sku, description, unit, unit_price, currency, tax_rate, active. Products are templates: invoice lines copy their values, so editing or deleting a product never changes an existing invoice.
Quotes & reports
GET|POST /quotes · GET|PATCH|DELETE /quotes/{id} · POST /quotes/{id}/send · POST /quotes/{id}/respond ({"decision":"accept"}) · POST /quotes/{id}/convert (accepted quotes only, once).
curl "https://flowzeen.com/api/v1/reports/revenue?currency=EUR&group=month" -H "Authorization: Bearer $FLOWZEEN_KEY"
{ "data": [ { "period": "2026-01", "invoices": 4, "invoiced": "5200.00", "received": "3100.00", "currency": "EUR" } ],
"meta": { "currency": "EUR", "totals": { ... }, "note": "Single-currency report. Amounts in different currencies are never combined." } }Webhooks
Add endpoints under Settings → Developer. Events: invoice.created, invoice.issued, invoice.sent, invoice.viewed, invoice.paid, invoice.cancelled, invoice.overdue, client.created, client.updated, product.created, product.updated, product.deleted, payment.recorded, quote.accepted. Delivery is retried with backoff (1 min, 5 min, 30 min, 2 h, 6 h, 24 h) up to 7 attempts; every delivery is logged. Each event has a unique id: deduplicate on it.
POST /your/endpoint
Content-Type: application/json
X-Flowzeen-Event: invoice.paid
X-Flowzeen-Event-Id: 5f0c…
X-Flowzeen-Timestamp: 1767225600
X-Flowzeen-Signature: t=1767225600,v1=<hex hmac>
{"id":"5f0c…","type":"invoice.paid","created":"2026-03-10T09:30:00+00:00","data":{"id":57,"number":"INV-2026-0007","currency":"EUR"}}$ts = (int) $_SERVER['HTTP_X_FLOWZEEN_TIMESTAMP'];
$body = file_get_contents('php://input');
if (abs(time() - $ts) > 300) { http_response_code(400); exit; } // replay protection
$expected = hash_hmac('sha256', $ts . '.' . $body, $signingSecret);
// header may contain two v1= values while a rotated secret overlaps (24 h)
$ok = false;
foreach (explode(',', $_SERVER['HTTP_X_FLOWZEEN_SIGNATURE']) as $part) {
if (str_starts_with($part, 'v1=') && hash_equals($expected, substr($part, 3))) { $ok = true; }
}
if (!$ok) { http_response_code(401); exit; }Respond with any 2xx status within 10 seconds. Redirects are not followed. Webhook failures never affect invoicing.
flowzeen is not a payment processor and does not guarantee legal compliance of invoices in any jurisdiction. See each country's capability status in Settings.