flowzeen API

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
ScopeGrants
invoices:read / invoices:writeList, read, create, edit drafts, issue, send, record payments, cancel
clients:read / clients:writeList, read, create, update, archive clients
quotes:read / quotes:writeList, read, create, update, send quotes; convert accepted quotes
reports:readRevenue 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 format
{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid data.",
    "fields": { "items.0.description": "Description is required." }
  }
}

Clients

Create a client — POST /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

Create a draft — POST /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": [ ... ] } }
Issue, send, record a payment
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).

Revenue report — GET /reports/revenue?from=2026-01-01&to=2026-12-31&currency=EUR&group=month
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.

Request
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"}}
Verify the signature (PHP)
$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.