Invoice document templates: authoring, per-document-type org defaults, duplication, and preview rendering.
List invoice templates
Lists invoice templates available to the caller's organization. The first page prepends built-in system defaults so the picker always has a baseline.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
document_typeFilter to templates supporting the document type (invoice, credit_note)
Filter to templates supporting the document type (invoice, credit_note)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List invoice templates › Responses
OK
Create an invoice template
Creates a new invoice template owned by the caller's organization. TemplateJSON is validated against the current schema and stamped with the current schema version on write.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create an invoice template › Request Body
descriptionFree-text description of the template.
document_typesDocument types this template can render (subset of {invoice, credit_note}); defaults to [invoice] when omitted.
nameTemplate name (required).
The template document: ordered blocks plus theme, branding, and footer.
Create an invoice template › Responses
Created
Get an invoice template
Returns a single template. Built-in system defaults are resolved from in-memory definitions; custom templates come from the org's repository.
path Parameters
idInvoice template ID
Invoice template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get an invoice template › Responses
OK
Delete an invoice template
Soft-deletes an org-owned invoice template. System defaults cannot be deleted.
path Parameters
idInvoice template ID
Invoice template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete an invoice template › Responses
No Content
Update an invoice template
Updates an org-owned invoice template. Requires expected_version for optimistic locking.
path Parameters
idInvoice template ID
Invoice template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update an invoice template › Request Body
expected_versionOptimistic-concurrency token: the version you last read. REQUIRED on this resource; a stale value answers 409 CONFLICT.
descriptionNew description; omit to leave unchanged.
document_typesNew set of renderable document types; omit to leave unchanged.
nameNew template name; omit to leave unchanged.
statusNew status (e.g. active, archived); omit to leave unchanged.
Replacement template document; omit to leave unchanged.
Update an invoice template › Responses
OK
Copy an invoice template
Creates a writable copy of the given template under the caller's organization. System defaults are copied by snapshotting the in-memory baseline.
path Parameters
idInvoice template ID
Invoice template ID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Copy an invoice template › Responses
Created
Mark an invoice template as the org default for a document type
Marks the given template as the organization's favorite for the document type in the path (invoice or credit_note). The favorite is per kind, so setting the credit-note favorite leaves the invoice favorite alone. System templates are valid targets.
path Parameters
idInvoice template ID
Invoice template ID
documentTypeWhich kind this template is the default for (invoice or credit_note)
Which kind this template is the default for (invoice or credit_note)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Mark an invoice template as the org default for a document type › Responses
OK
Clear the org default for a document type
Clears this template's favorite slot for the document type in the path. Rendering for that kind falls back to the system default - never to nothing. Only succeeds if this template currently holds the slot. Returns the template with its updated default memberships.
path Parameters
idInvoice template ID
Invoice template ID
documentTypeWhich kind this template is the default for (invoice or credit_note)
Which kind this template is the default for (invoice or credit_note)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Clear the org default for a document type › Responses
OK
Render an invoice template preview PDF
Renders a sample PDF using the stored template, or - if a template_json body is supplied - using that unsaved draft. Rendered output is short-TTL cached so repeated calls return identical bytes. Rate-limited per organization.
path Parameters
idInvoice template ID
Invoice template ID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Render an invoice template preview PDF › Request Body
document_typeSingle document type to render; defaults to INVOICE.
document_typesDocument types to render (e.g. INVOICE, CREDIT_NOTE); defaults to the template's.
Unsaved template draft to preview instead of the stored template.
Render an invoice template preview PDF › Responses
PDF file
Get an invoice-template thumbnail SVG
A lightweight SVG schematic of the template (block layout in theme colors) suitable for picker cards. Strongly cached with an ETag keyed on updated_at - clients should send If-None-Match.
path Parameters
idInvoice template ID
Invoice template ID
Headers
If-None-MatchConditional request: prior ETag
Conditional request: prior ETag
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get an invoice-template thumbnail SVG › Responses
SVG thumbnail