Skip to content

Templates and pay themes

Explore here
Copy as markdownView as markdown

Templates and pay themes

How an invoice and its pay page look. Drafts only; publishing is an approved action.

All sectionsAuthentication

templates

List

GET/v1/templates

Invoice templates, drafts and published, newest first.

Scope
templates:read
Effect
Read only
MCP tool
list_templates
Retries
Safe to repeat

Parameters

List parameters
NameInTypeNotes
limitoptionalqueryintegermin 1 · max 50
cursoroptionalquerystringup to 256 chars
stateoptionalqueryenumOne of draft, published

Returns

data: Template[]. Pass meta.cursor back as cursor for the next page.

Example requestSample
curl -X GET "https://api.billingmart.com/v1/templates" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

templates

Create

POST/v1/templates

Create a DRAFT invoice template. Server-side the same block validation the console runs; `state` is forced to draft and publication fields are refused.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
create_template_draft
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Create request body
FieldTypeNotes
businessIdrequiredid—
namerequiredstringup to 120 chars
pageSizeoptionalenumOne of a4, letter
accentTokenNameoptionalstringup to 64 chars
blocks[]requiredobject[]up to 30 items · at least 1
blocks[].kindrequiredstringup to 40 chars
blocks[].textoptionalstringup to 500 chars
blocks[].alignoptionalenumOne of start, center, end
blocks[].visibleoptionalboolean—
blocks[].spacingStepsoptionalintegermin 0 · max 12

Returns

data: object

Example requestSample
curl -X POST "https://api.billingmart.com/v1/templates" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","name":"<name>"}'

templates

Get

GET/v1/templates/{templateId}

One invoice template with its blocks.

Scope
templates:read
Effect
Read only
MCP tool
get_template
Retries
Safe to repeat

Parameters

Get parameters
NameInTypeNotes
templateIdrequiredpathid—

Returns

data: Template

Example requestSample
curl -X GET "https://api.billingmart.com/v1/templates/{templateId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

templates

Update

PATCH/v1/templates/{templateId}

Edit a DRAFT invoice template. A published template is immutable and is refused.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
update_template_draft
Retries
No Idempotency-Key on this route

Parameters

Update parameters
NameInTypeNotes
templateIdrequiredpathid—

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Update request body
FieldTypeNotes
nameoptionalstringup to 120 chars
pageSizeoptionalenumOne of a4, letter
accentTokenNameoptionalstringup to 64 chars
blocks[]optionalobject[]up to 30 items · at least 1
blocks[].kindrequiredstringup to 40 chars
blocks[].textoptionalstringup to 500 chars
blocks[].alignoptionalenumOne of start, center, end
blocks[].visibleoptionalboolean—
blocks[].spacingStepsoptionalintegermin 0 · max 12

Returns

data: Template

Example requestSample
curl -X PATCH "https://api.billingmart.com/v1/templates/{templateId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

templates

Preview

GET/v1/templates/{templateId}/preview

Render an invoice template — draft or published — over a sample invoice and return a short-lived signed URL. Nothing is sent and no real invoice is used.

Scope
templates:read
Effect
Read only
MCP tool
preview_template_pdf
Retries
Safe to repeat

Parameters

Preview parameters
NameInTypeNotes
templateIdrequiredpathid—

Returns

data: PdfPreview

Example requestSample
curl -X GET "https://api.billingmart.com/v1/templates/{templateId}/preview" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

templates

Generate

POST/v1/templates/generate

Design a DRAFT invoice template from a description. It is a draft: no invoice or PDF uses it until a person approves publishing it.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
generate_template_draft
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Generate request body
FieldTypeNotes
businessIdrequiredid—
descriptionrequiredstringat least 10 chars · up to 2000 chars

Returns

data: object

Errors this route can answer besides the shared ones: AI_DISABLED, AI_CAP_REACHED, AI_CREDITS_EXHAUSTED.

Example requestSample
curl -X POST "https://api.billingmart.com/v1/templates/generate" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","description":"<description>"}'

pay themes

Generate

POST/v1/pay-themes/generate

Design a DRAFT pay-page theme from a description. It renders nowhere until a person approves publishing it.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
generate_pay_theme_draft
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Generate request body
FieldTypeNotes
businessIdrequiredid—
descriptionrequiredstringat least 10 chars · up to 2000 chars

Returns

data: object

Errors this route can answer besides the shared ones: AI_DISABLED, AI_CAP_REACHED, AI_CREDITS_EXHAUSTED.

Example requestSample
curl -X POST "https://api.billingmart.com/v1/pay-themes/generate" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","description":"<description>"}'

pay themes

List

GET/v1/pay-themes

Pay-page themes, drafts and published, newest first.

Scope
templates:read
Effect
Read only
MCP tool
list_pay_themes
Retries
Safe to repeat

Parameters

List parameters
NameInTypeNotes
limitoptionalqueryintegermin 1 · max 50
cursoroptionalquerystringup to 256 chars
stateoptionalqueryenumOne of draft, published

Returns

data: PayPageTheme[]. Pass meta.cursor back as cursor for the next page.

Example requestSample
curl -X GET "https://api.billingmart.com/v1/pay-themes" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

pay themes

Create

POST/v1/pay-themes

Create a DRAFT pay-page theme. The three seam tokens must be present and pass the contrast check in both themes; `logoUrl` must be inside this tenant’s own Storage prefix.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
create_pay_theme_draft
Retries
Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Create request body
FieldTypeNotes
businessIdrequiredid—
namerequiredstringup to 120 chars
headlinerequiredstringup to 120 chars · matches ^[^<]*$
subheadlineoptionalstringup to 200 chars · matches ^[^<]*$
layoutrequiredenumOne of single, split
showLineItemsrequiredboolean—
logoUrloptionalstringup to 512 chars
tokenOverridesrequiredobject—

Returns

data: object

Example requestSample
curl -X POST "https://api.billingmart.com/v1/pay-themes" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"businessId":"<businessId>","name":"<name>","headline":"<headline>","layout":"single","showLineItems":false,"tokenOverrides":{}}'

pay themes

Get

GET/v1/pay-themes/{themeId}

One pay-page theme.

Scope
templates:read
Effect
Read only
MCP tool
get_pay_theme
Retries
Safe to repeat

Parameters

Get parameters
NameInTypeNotes
themeIdrequiredpathid—

Returns

data: PayPageTheme

Example requestSample
curl -X GET "https://api.billingmart.com/v1/pay-themes/{themeId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

pay themes

Update

PATCH/v1/pay-themes/{themeId}

Edit a DRAFT pay-page theme. A published theme is immutable and is refused.

Scope
templates:write
Effect
Writes a draft or record
MCP tool
update_pay_theme_draft
Retries
No Idempotency-Key on this route

Parameters

Update parameters
NameInTypeNotes
themeIdrequiredpathid—

Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Update request body
FieldTypeNotes
nameoptionalstringup to 120 chars
headlineoptionalstringup to 120 chars · matches ^[^<]*$
subheadlineoptionalstringup to 200 chars · matches ^[^<]*$
layoutoptionalenumOne of single, split
showLineItemsoptionalboolean—
logoUrloptionalstringup to 512 chars
tokenOverridesoptionalobject—

Returns

data: PayPageTheme

Example requestSample
curl -X PATCH "https://api.billingmart.com/v1/pay-themes/{themeId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"

Object

Template

An InvoiceTemplate document — a STRUCTURED DOCUMENT, never markup. The AI emits schema-validated JSON and never HTML, CSS or script; out-of-schema fields are discarded, not stored. A generated template is a DRAFT until a human publishes it. The renderer is a real pdf-lib renderer, so what is previewed is what is sent.

Template fields
FieldTypeNotes
idrequiredId—
tenantrequiredTenantRef—
namerequiredstringUntrusted text—
staterequiredPublishState—
originoptionalenumai is what makes the draft-until-published rule non-negotiable. api is a draft written through REST or MCP: still a draft until a person publishes it.
blocksrequiredTemplateBlock[]Ordered layout blocks. A closed vocabulary is the point: an open one is markup with extra steps.
pageSizeoptionalenum—
accentTokenNameoptionalstringA semantic token name from brand/tokens, not a hue. A consumer that references blue-500 cannot be re-themed.
rationaleoptionalstringUntrusted textThe Designer's one or two sentences on why this layout fits. Shown to the person editing, never rendered on the invoice.
aiRawoptionalstringThe model's raw answer, verbatim and digit-masked, kept beside the human-edited copy so "what did it actually propose" survives the edit. Written by the generator, never by a client.
createdByoptionalId—
publishedAtoptionalIsoTimestamp—
publishedByoptionalIdThe human who published. Absent while draft — an AI cannot fill this in.
createdAtrequiredIsoTimestamp—
updatedAtoptionalIsoTimestamp—
lastWriteActoroptionalWriteActorWho last wrote this record, and when — stamped by the server core. An EDIT_CONFLICT names it, so the person refused knows who saved the newer version.

Object

PayPageTheme

PayPageTheme is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Next section

Messages and activity

The delivery log of every email and text, the audit trail of who did what, and your own notifications and their settings.

Continue to Messages and activity →

Try it against your sandbox

Create a bmk_test_ key in the console. It can only reach your sandbox workspace.

Start freeAll sections

We use Google Analytics on our website by default to understand visits. Choose Decline to turn it off; you can change this at any time on the Cookies page. We never send Google your name, email or account. Cookie policy