# Recurring Templates

> Automate recurring invoices and bills with customizable schedules.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/recurring
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Recurring Templates

Recurring templates automatically generate invoices, bills or journal entries on a schedule. Set up a template once and DayZero creates the documents at the configured frequency.

## Create a Recurring Template

A template has a **schedule** (top-level fields) and the **document to generate** (`template_data`):

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme monthly retainer",
    "recurrence_type": "invoice",
    "customer_id": "CUSTOMER_UUID",
    "frequency": "monthly",
    "day_of_month": 1,
    "start_date": "2026-11-01",
    "days_until_due": 30,
    "auto_send": false,
    "template_data": {
      "description": "Monthly retainer",
      "line_items": [
        {
          "description": "Monthly retainer",
          "quantity": 1,
          "unit_price": 250000
        }
      ]
    }
  }'
```

> `unit_price` is in cents. `250000` = $2,500.00 per month.

A recurring bill:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office rent",
    "recurrence_type": "bill",
    "vendor_id": "VENDOR_UUID",
    "frequency": "monthly",
    "day_of_month": 1,
    "days_until_due": 15,
    "start_date": "2026-11-01",
    "template_data": {
      "description": "Office rent for 123 Main St",
      "amount": 350000
    }
  }'
```

### Schedule fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Template name |
| `recurrence_type` | Yes | `invoice`, `bill` or `journal_entry` |
| `frequency` | Yes | `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `annually` |
| `start_date` | Yes | First generation date |
| `customer_id` | For invoices | Customer to bill |
| `vendor_id` | For bills | Vendor the bill is from |
| `day_of_month` | No | 1–31 for monthly/quarterly/annually; clamps to the last day of shorter months. Defaults to the day in `start_date` |
| `day_of_week` | No | 0 = Monday … 6 = Sunday for weekly/biweekly. Defaults to the weekday of `start_date` |
| `days_until_due` | No | Days from generation to due date (default `30`) |
| `end_date` / `max_occurrences` | No | Stop after a date or a count — whichever comes first. Both `null` = indefinite |
| `auto_send` | No | Email each generated invoice to the customer automatically (default `false`) |
| `currency` | No | `USD` (default), `CAD`, `AUD`, `EUR`, `GBP` |
| `contract_id` | No | Invoice templates only — routes generated invoices into the contract's billing tallies |

### `template_data` by type

| Type | Keys |
|------|------|
| `invoice` | `line_items` (same shape as [invoice line items](/docs/guides/invoices)), optional `description`, `project_id` |
| `bill` | `amount` (cents) and `description`. Generated bills are created as `forecasted`, `type: recurring` |
| `journal_entry` | `line_entries` (same shape as [journal entry lines](/docs/guides/journal-entries)), optional `description` |

## List Templates

```bash
curl "https://api.ondayzero.com/api/v1/recurring?recurrence_type=invoice&status=active" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Filter Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `recurrence_type` | string | `invoice`, `bill` or `journal_entry` |
| `status` | string | `active`, `paused`, `completed`, `cancelled` |
| `customer_id` | UUID | Filter invoice templates by customer |
| `vendor_id` | UUID | Filter bill templates by vendor |
| `search` | string | Match on template name |

Plus the standard [pagination](/docs/guides/pagination) parameters. Shortcut endpoints are also available:

- `GET /api/v1/recurring/invoices` — only invoice templates
- `GET /api/v1/recurring/bills` — only bill templates

`POST /api/v1/recurring/suggest-templates` asks the AI to find repeating invoices and bills that could become templates.

## Manage Template Lifecycle

### Pause

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring/{template_id}/pause" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Resume

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring/{template_id}/resume" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Cancel

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring/{template_id}/cancel" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Cancelling is permanent (status `cancelled`); use pause if you may want to resume. `DELETE /api/v1/recurring/{template_id}` removes the template entirely; documents it already generated are kept.

### Skip Next Occurrence

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring/{template_id}/skip" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Update

`PUT /api/v1/recurring/{template_id}` changes any schedule field or the `template_data`; changes apply from the next generation onward. `recurrence_type` cannot be changed — clone instead.

## View Generation History

See all documents generated from a template:

```bash
curl "https://api.ondayzero.com/api/v1/recurring/{template_id}/history?limit=10" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

## Clone a Template

Copy a template, optionally pointing it at a different customer or vendor and a new start date:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/recurring/{template_id}/clone" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Globex monthly retainer", "customer_id": "OTHER_CUSTOMER_UUID", "start_date": "2026-12-01"}'
```