API Reference Overview

Base URL: https://invoicepdfs.com

Endpoints

Group	Endpoints	Description
Health & Status	GET /health, /ready, /version	Service health and readiness checks
API Keys	POST/GET /api/v1/api-keys	Create, list, and revoke API keys
Business Profiles	CRUD /api/v1/business-profiles	Seller/company profiles
Customers	CRUD /api/v1/customers	Customer/buyer records
Documents	CRUD /api/v1/documents	Managed invoice/document lifecycle
Documents (stateless)	POST /api/v1/documents/{validate,calculate,render}	Stateless validate, calculate, and render
Templates	GET /api/v1/templates	List and preview templates
Renders	GET /api/v1/renders/{id}/download	Download rendered PDFs
Deliveries	GET /api/v1/deliveries/{id}	Email delivery tracking
Files	POST/GET/DELETE /api/v1/files	Logo and attachment uploads
Workspaces	CRUD /api/v1/workspaces	Team workspaces and members
Usage	GET /api/v1/usage	Quota and usage info
Error Handling	—	Error codes and response format

Common Patterns

Request Format

All request bodies use JSON with Content-Type: application/json.

Response Envelope

All responses are wrapped in a data envelope:

{
  "data": { ... }
}

Errors use an error envelope:

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "Document not found",
    "request_id": "req_01ABC"
  }
}

See Error Handling for the full list of error codes.

Pagination

List endpoints support cursor-based pagination:

GET /api/v1/documents?limit=25&cursor=eyJjcmVhdGVkX2F0Ijo...

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0Ijo..."
  }
}

Idempotency

Write endpoints accept an Idempotency-Key header to prevent duplicate operations:

curl -X POST /api/v1/documents/render \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Partial Updates (PATCH)

A PATCH body carries only the fields you want to change. Every field is optional, and there are three things you can say about one:

In the body	Meaning
field omitted	leave it as it is
"field": "value"	set it to that value
"field": null	clear it

# Remove a customer's tax ID and billing address, leaving everything else alone
curl -X PATCH /api/v1/customers/cus_01ABC \
  -H "Content-Type: application/json" \
  -d '{"tax_id": null, "billing_address": null}'

A field that must always have a value cannot be cleared, and the schema says which those are: on PATCH /api/v1/customers/{id} the name is string, while email is string | null. Sending null for one of the first kind is a 422 naming the field, not a silent no-op:

{
  "error": {
    "status": 422,
    "code": "unprocessable_entity",
    "message": "Request validation failed",
    "details": { "fields": [{ "loc": "body.name", "msg": "Input should be a valid string" }] }
  }
}

The official SDKs model all three states directly — the Go client, for instance, gives every clearable field a SetXNil() alongside its SetX() and UnsetX().

Money Fields

All monetary values are represented as decimal strings with a currency code:

{
  "amount": "1500.00",
  "currency": "USD"
}

Decimal Strings

Quantities, unit prices, tax rates, and discount values are all decimal strings to avoid floating-point precision issues:

{
  "quantity": "2.5",
  "unit_price": "49.99",
  "rate": "8.875"
}

Interactive API Docs

The Swagger UI is available at /api/v1/docs for interactive testing.