# Invoice Templates

How invoice appearance is controlled.

---

## Overview

> **Note:** there is no invoice template API. Endpoints such as `/api/v1/invoices/templates/:templateId`, custom template fields, per-template typography, localization and editable email/PDF layouts are not available.

Every invoice uses the platform's standard layout for the PDF, the invoice email and the hosted pay page. What you control is the **merchant's branding**, which all three pick up automatically:

- 🖼️ **Logo** - light and dark variants
- 🎨 **Primary color** - headings, totals and the pay button in the PDF
- 🏢 **Business details** - business name, address and contact email (from the merchant profile)

---

## Get Branding

### Endpoint

```http
GET /api/v1/merchants/:merchantId/branding
```

```bash
curl https://uat.auxcore.net/api/v1/merchants/6f1c2a9e-3b7d-4e21-9a55-0c8f1d2b7e40/branding \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"
```

Use `me` as `:merchantId` for the merchant of the signed-in user.

---

## Update Branding

### Endpoint

```http
PUT /api/v1/merchants/:merchantId/branding
```

```bash
curl -X PUT https://uat.auxcore.net/api/v1/merchants/6f1c2a9e-3b7d-4e21-9a55-0c8f1d2b7e40/branding \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "logoUrl": "https://cdn.example.com/logo.png",
    "logoDarkUrl": "https://cdn.example.com/logo-dark.png",
    "primaryColor": "#2c3e50"
  }'
```

Only the fields you send are changed. To upload logo files instead of URLs, use `POST /api/v1/merchants/:merchantId/branding/upload` (multipart). See [Merchant Branding](../merchants/branding.md) for every branding field.

---

## What the Invoice Uses

| Branding field | Used for |
|----------------|----------|
| `logoData` / `logoUrl` | Logo in the PDF header (the AuxCORE logo is used when none is set) |
| `logoDarkUrl` | Logo when `darkMode` is on |
| `primaryColor` | Accent color in the PDF |

The business name, address and contact email come from the merchant's business profile, not from branding. The name printed is the DBA name, falling back to the Business Name (`companyName`).

---

## What Each Invoice Carries

Per-invoice content is set on the invoice itself (see [Invoices](./invoices.md)):

| Invoice field | Shown as |
|---------------|----------|
| `invoiceNumber` | Invoice number (`INV-YYYY-NNNNNN`, or the external number for synced invoices) |
| `issueDate` / `dueDate` | Issue and due dates (invoices have no expiry date) |
| `customerName`, `customerEmail`, billing address | Bill-to block |
| `lineItems` | Line items with quantity, unit, price, discount and tax |
| `subtotal`, `discountAmount`, `taxAmount`, `totalAmount`, `amountDue` | Totals |
| `notes`, `terms`, `poNumber`, `reference` | Notes and references |
| `shortLink` / `linkId` | Pay button and QR code |

---

## Recurring Invoices

Recurring invoices (`type: "recurring"`) are generated by copying the original invoice on each cycle. That copy is internal to the platform; there is no API to manage invoice templates directly.

---

## Best Practices

### ✅ DO:
- **Use a high-resolution logo** - it is scaled down for the PDF
- **Provide a dark-mode logo** if you enable `darkMode`
- **Brand consistently** - Match your website colors
- **Keep business details current** - they print on every invoice

### ❌ DON'T:
- **Don't use a low-contrast primary color** - totals and the pay button use it

---

## Next Steps

- [Create invoices →](./invoices.md)
- [Send invoices →](./sending.md)
- [Merchant branding →](../merchants/branding.md)

---

**Need help?** Contact support@auxcore.net