> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcenpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice builder

> Design provider-branded invoices — logos, colors, fonts, watermark — with immutable design snapshots and on-demand PDFs. Available on Plus and Pro.

The invoice builder lets Plus/Pro providers design the invoices, receipts and emailed documents their customers receive — logo, brand colors, fonts, watermark and section layout — with a live preview in the dashboard.

## Availability & tier gating

* **FREE** — no builder (the dashboard hides the section). Invoices render with the standard ArcenPay layout.
* **PLUS / PRO** — full builder: create, edit, activate, duplicate, and (for custom templates only) delete templates.
* **White-label** — Plus/Pro can also remove the "Secured by ArcenPay" badge from their embedded billing page (`component-render` enforces this server-side).

## How it works

1. **Seeded default.** On first visit, Plus/Pro teams get an active **"Classic"** template. The seeded default is **protected** — it can be edited and published but never deleted (`403 PROTECTED_TEMPLATE` on delete).
2. **Design.** Change colors, font, orientation, logo (PNG/JPEG, uploaded to object storage), section visibility (header, metadata, addresses, items table, totals, footer), column widths, watermarks (e.g. `PAID` / `OVERDUE`) and footer notes. A **live PDF preview** updates as you edit.
3. **Publish.** Activating a template makes it the active design. Only one template is active per environment scope.
4. **Immutability.** The design is **snapshotted onto every invoice at its first render**. Editing or replacing the template never changes invoices that were already issued.

## On-demand PDFs (Stripe-style)

Invoices and receipts are **never stored as files**. A signed, expiring download URL renders the PDF live from the invoice object:

* `GET /api/v1/invoices/:id/download` — issue a signed render URL (dashboard session).
* `GET /api/invoices/public/:id/download?kind=invoice|receipt&exp=…&sig=…` — public render endpoint; signature is HMAC-SHA256 over `invoiceId.kind.exp`.
* Receipts are only available for `PAID` invoices and derive their number deterministically.

## Template endpoints

| Method & path                                   | Purpose                                              |
| ----------------------------------------------- | ---------------------------------------------------- |
| `GET /api/v1/invoices/templates`                | List templates (`storage.driver` also returned)      |
| `POST /api/v1/invoices/templates`               | Create a template (Plus/Pro only)                    |
| `GET /api/v1/invoices/templates/:id`            | Fetch one template incl. its config                  |
| `PATCH /api/v1/invoices/templates/:id`          | Update name/config                                   |
| `DELETE /api/v1/invoices/templates/:id`         | Delete (never the protected default → `403`)         |
| `POST /api/v1/invoices/templates/:id/activate`  | Publish a template                                   |
| `POST /api/v1/invoices/templates/:id/duplicate` | Duplicate a template                                 |
| `POST /api/v1/invoices/templates/preview`       | Render a draft config as PDF (live preview)          |
| `POST /api/v1/invoices/templates/logo`          | Upload a logo (PNG/JPEG ≤ 2MB, magic-byte validated) |
| `GET /api/v1/invoices/templates/default-config` | The stock "Classic" config (starting point)          |

All template routes require `invoices:read` / `invoices:write` roles. Write routes additionally enforce the **`invoiceBuilder`** tier feature (FREE → `402 INVOICE_BUILDER_REQUIRES_UPGRADE`).

## Object storage

Logos and future assets are stored through a pluggable object store (`STORAGE_DRIVER=r2` for Cloudflare R2, `local` filesystem fallback). Asset reads for rendering go through the same store — no external bucket permissions are needed by your customers.