Layouts for invoices, quotes and other documents: create, copy, preview and set a template as your organization's default for a document type.
List document templates
Lists every document template the caller's organization has authored - printed layouts (invoice, credit note, quote) AND email templates, which are a document type of their own. An email row carries anchor_key and the anchor's human name in the request locale; printed rows carry neither. Filter with document_type when you are filling a printed-document picker, because preview-as-PDF and make-this-the-default are meaningless on an email. Filter with status to narrow the lifecycle (printed templates are active or archived, emails are draft, published or archived); omit it to include archived ones. Ask for counts=document_type to get the per-kind tallies a filter-chip bar renders, taken in the same read. The first page prepends built-in system defaults so a picker always has a baseline.
Required scope: invoice.read (Read invoices).
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.
sortOrdering: updated_at, with an optional :asc/:desc suffix (default updated_at:desc, most recently edited first). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
document_typeFilter to templates supporting one document type (invoice, credit_note, quote or email); omit for all kinds, email included.
statusFilter to one lifecycle status. Omit to include every status, archived ones included. Printed templates are active or archived; email templates are draft, published or archived.
anchor_keyFilter to the email templates written for one mail kind, e.g. "invoice.finalized". Implies email: a printed template has no anchor.
countsComma-separated facet fields to tally for filter chips. Only "document_type" is supported; it returns counts.document_type.{all,invoice,credit_note,quote,email}.
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 document templates › Responses
OK
Create a document template
Creates a new document template owned by the caller's organization. TemplateJSON is validated against the current schema and stamped with the current schema version on write.
Required scope: invoice.write (Write invoices).
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 a document template › Request Body
descriptionFree-text description of the template.
nameTemplate name (required).
The template document: ordered blocks plus theme, branding, and footer.
document_typesDocument types this template can render (subset of {invoice, credit_note, quote, email}); defaults to [invoice] when omitted.
Create a document template › Responses
Created
Get a document template
Returns a single template. Built-in system defaults are resolved from in-memory definitions; custom templates come from the org's repository.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument 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 a document template › Responses
OK
Delete a document template
Soft-deletes an org-owned document template. System defaults cannot be deleted.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument 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 a document template › Responses
No Content
Update a document template
Updates an org-owned document template. Requires expected_version for optimistic locking.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument 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 a document 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 (active or archived); omit to leave unchanged.
Replacement template document; omit to leave unchanged.
Update a document template › Responses
OK
List what a document template leaves out
Measures the stored template - or, with template_json, the unsaved draft - and returns the builder's advisory checklist: what the law of the organization's own country requires on an invoice and a credit note that the layout cannot print, the essential facts of a quote a surface leaves out, what the web needs for the buyer to accept online, and what the quote presets rendering through the template carry. Each row names its legal basis where it has one and the one change that resolves it. Nothing in it is enforced.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument 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.
List what a document template leaves out › Request Body
document_typesDocument types the unsaved draft renders; defaults to the stored template's. Read only with template_json.
Unsaved template draft to measure instead of the stored template.
List what a document template leaves out › Responses
OK
Copy a document template
Creates a writable copy of the given template under the caller's organization. System defaults are copied by snapshotting the in-memory baseline.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument 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 a document template › Responses
Created
Mark a document 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, credit_note or quote). The favorite is per kind, so setting the credit-note favorite leaves the invoice and quote favorites alone. System templates are valid targets.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument template ID
documentTypeWhich kind this template is the default for (invoice, credit_note or quote)
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 a document 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.
Required scope: invoice.write (Write invoices).
path Parameters
idDocument template ID
documentTypeWhich kind this template is the default for (invoice, credit_note or quote)
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 a document 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.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument 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 a document template preview PDF › Request Body
document_typeThe one document type to render; defaults to the first type the template declares.
document_typesDocument types the unsaved draft renders; defaults to the stored template's. Read only with template_json.
scenarioThe sample offer a quote preview renders: simple (the default), ramp, usage, update, multi_subscription or reverse_charge. Read only when the preview renders a quote.
Unsaved template draft to preview instead of the stored template.
Render a document template preview PDF › Responses
PDF file
Lay a quote template out over a sample offer
Plans the stored quote template - or, with template_json, the unsaved draft - over one of the sample offers (scenario) for one surface (print or web): the sample's document model, the blocks the surface draws, and the facts each block states: its own content and what its switches repeat. The builder's canvas renders the sample through it and dims the blocks that state nothing. A template that does not render quotes is refused.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument 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.
Lay a quote template out over a sample offer › Request Body
document_typesDocument types the unsaved draft renders; defaults to the stored template's. Read only with template_json.
scenarioThe sample offer: simple (the default), ramp, usage, update, multi_subscription or reverse_charge.
surfaceThe surface to plan for: print (the default) or web.
Unsaved template draft to plan instead of the stored template.
Lay a quote template out over a sample offer › Responses
OK
Get a document-template thumbnail SVG
A lightweight SVG schematic of the template (block layout in theme colors) suitable for picker cards. Cached privately with an ETag derived from the drawing - clients should send If-None-Match.
Required scope: invoice.read (Read invoices).
path Parameters
idDocument template ID
Headers
If-None-MatchConditional 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 a document-template thumbnail SVG › Responses
SVG schematic