Templates API
Create and manage reusable invoice presentation and default document settings.
Templates control invoice presentation, branding, default currency, invoice number prefix, payment terms, notes, and terms and conditions.
/v1/receivables/templatesEndpoints and Schemas
| Method | Path | Request schema | Success response |
|---|---|---|---|
GET | / | query: limit, offset | TemplatesResponse |
POST | / | CreateTemplateRequest | TemplateResponse |
GET | /default | none | TemplateResponse |
GET | /{id} | none | TemplateResponse |
PATCH | /{id} | UpdateTemplateRequest | TemplateResponse |
DELETE | /{id} | none | DeleteTemplateResponse |
POST | /{id}/set-default | none | TemplateResponse |
POST | /{id}/duplicate | none | TemplateResponse |
Create Request
| Field | Type | Needed | Default or constraint |
|---|---|---|---|
name | string | yes | 1–255 characters. |
templateType | enum | no | default, modern, classic, minimal, or professional; default default. |
baseColor | string | no | Hex brand color; default #3B82F6. |
mode | enum | no | light or dark; default light. |
currency | string | no | ISO 4217 code; default USD. |
prefix | string | no | Default invoice number prefix; default INV-. |
paymentTerms | string | no | Default Net 30. |
notes | string or null | no | Default invoice footer notes. |
terms | string or null | no | Default terms and conditions. |
isDefault | boolean | no | Default false; setting true unsets the previous default. |
{
"name": "Northwind Standard",
"templateType": "professional",
"baseColor": "#1D4ED8",
"mode": "light",
"currency": "USD",
"prefix": "NW-",
"paymentTerms": "Net 30",
"notes": "Thank you for your business.",
"isDefault": true
}Response Contract
TemplateResponse.data includes the saved fields plus id, userId, createdAt, and updatedAt. The built-in template can use the literal identifier system-default. Custom templates use UUIDs.
Updates are partial. Invoices and PDFs from before the update can keep their saved presentation or content. Regenerate a document only after you confirm the intended invoice state.
Default and Deletion Behavior
Only one template can be default at a time. Fetch /default when you create a new invoice. Do not cache the default indefinitely. If historical continuity matters, duplicate or retire a template in your client workflow. Do not assume that deletion changes the documents that you already issued.