Invoice REST API documentation

Authentication

All requests must include a bearer token. Create keys in your dashboard. Keys look like invd_live_… and are shown only once.

Authorization: Bearer invd_live_YOUR_KEY

There is no separate test key today — every invd_live_ key writes to your real account. Use a separate test account for experiments. A dedicated key in your main account still has access to that account’s invoices; revoking it does not undo writes.

Base URL

https://pskmcpbbmvhczxzlazom.supabase.co/functions/v1/api-v1

Use your deployment’s Supabase project URL followed by /functions/v1/api-v1. Replace YOUR_PROJECT and all key placeholders before running examples. First call GET /me to check authentication without creating an invoice. The private website preview does not confirm API availability.

Endpoints

Pagination

GET /invoices accepts either ?offset= (simple) or ?cursor= (recommended for large lists, using created_at and id ordering). The response includes next_cursorwhen more rows are available; pass it as ?cursor= on the next call.

The default limit is 50 and the maximum is 200. Use positive integers, URL-encode the returned cursor and keep the same status filter on subsequent pages. Stop when next_cursor is null. Cursor responses omit count and offset.

GET /invoices?limit=50
{"data": [...], "next_cursor": "2026-07-03T12:34:56.789Z_ab12..."}

GET /invoices?limit=50&cursor=2026-07-03T12:34:56.789Z_ab12...

Webhooks

Register endpoints in the webhooks dashboard. We POST signed JSON on invoice.created, invoice.updated, invoice.deleted. Verify with:

// Node.js verify
import crypto from "crypto";
const sig = req.headers["x-invoodle-signature"];
// rawBody must be the original request bytes, before JSON parsing.
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (typeof sig !== "string") throw new Error("missing signature");
const actualBytes = Buffer.from(sig);
const expectedBytes = Buffer.from(expected);
if (actualBytes.length !== expectedBytes.length ||
    !crypto.timingSafeEqual(actualBytes, expectedBytes)) {
  throw new Error("bad signature");
}

The dispatcher allows four total attempts with a 10-second request timeout. After failures it records retry times of 1, 5 and 30 minutes; a separate scheduler must invoke pending deliveries. No retry scheduler is included in the current source. Return a 2xx response promptly, queue your work and deduplicate using X-Invoodle-Delivery. The signed body contains id, event, created_at and data; created_at is generated per attempt, so it is not a stable event timestamp.

Rate limits & audit

Each API key is limited to 60 requests per minute (sliding window). Over-limit requests return 429 Too Many Requests. Usage logging is best effort for authenticated requests; failed authentication is not included. Inspect activity — see the usage dashboard. The count-based limiter can allow concurrent bursts and allows requests if its usage store is unavailable.

Idempotency

POST /invoices is not idempotent — retrying the same request creates a new invoice each time. An invoice number is not a uniqueness constraint, and checking a list before writing does not prevent concurrent duplicates. Record the returned invoice id in your integration. If a create request times out, reconcile the account’s records before retrying; use your own durable operation tracking. The API does not support an Idempotency-Key header.

Status codes

Error format

{ "error": "Invalid or revoked API key" }

Standard HTTP codes: 200/201 on success, 204 on delete, 400 for validation, 401 for auth, 404 for missing resources, 500 for server errors.