# Recurring templates: quarterly, yearly, and an invoice cap

Templates gain quarterly and yearly cadences, an end after `max_invoices`, a `completion` reason, `draft_in_advance`, and the amount of the next invoice on every row.

Sep 15, 2026 · New

Recurring templates stop being monthly-only, stop being open-ended-or-dated-only, and start telling you what they are going to charge.

Everything here is additive: a template you create today the way you created it yesterday behaves identically.

## What else changed

- **`frequency` accepts `MONTHLY`, `QUARTERLY` and `YEARLY`** — every 1, 3 or 12 months, on the same `day_of_month` anchor. Omitted, `MONTHLY` applies. The cadence governs the step from the first invoice onwards, not where the first one lands: a yearly template starting 15 February with `day_of_month` 10 first invoices on 10 March, then every 10 March — it does not wait a year.
- **`max_invoices` ends the recurrence by number** (2 to 600). It is the **total agreed**, not what is left: remaining is `max_invoices - generated_invoices`, and there is deliberately no second field for it. What counts against it is invoices *generated*, so a skip does not spend cap and a generate-now does. A recurrence ends in exactly one way — open-ended, on `end_date`, or after `max_invoices`.
- **`completion` says why a template ended**: `USER`, `END_DATE_REACHED` or `MAX_INVOICES_REACHED`, with the instant in `at`. `status` keeps its three values and `COMPLETED` stays a single terminal status, so nothing breaks an exhaustive `switch` — new causes land in `reason`, so treat it as an open set. Templates completed before this was recorded carry no `completion`, because that cause is not known and is not invented.
- **`draft_in_advance` replaces `preview_days`.** The review window is no longer a number you pick: it is fixed at 5 days. `preview_days` is deprecated and still accepted — any value above `0` means `draft_in_advance: true`, `0` means `false`, and if both arrive `draft_in_advance` wins. Either way the invoice is emitted on the scheduled day; what changes is whether there is a draft to look at first.
- **`amount` on every template** — what the customer will be asked to transfer on the next invoice it generates: base + VAT + equivalence surcharge − withholding + disbursements. The same number the next occurrence publishes as `total_to_pay`, to the cent. It is computed on the fly, so it always matches the lines the template carries right now — and for that reason it is not sortable or filterable. `null` when the lines cannot be priced.
- **`day_of_month: 31` is how you ask for the last day of the month.** A month without that day falls back to its last one — 28 February, 30 April — and the adjustment never sticks: every generation is recalculated from the value you sent, so the schedule does not drift.
- **Three more fields on the response**: `payment_iban`, `payment_swift` and `payment_term_days` of the template's own payment method, and `recipient_alternative_id` for a recipient identified by something other than a Spanish NIF (mutually exclusive with `recipient_nif`).
- **`start_date` is a no-op when you resend the value it already has**, instead of being rejected once the template has issued — so a read-modify-write cycle no longer has to strip the field out of the body.

## Endpoints

- `POST /v1/companies/{company_id}/recurring-invoices` — frequency QUARTERLY|YEARLY, max_invoices, draft_in_advance
- `GET /v1/companies/{company_id}/recurring-invoices` — Every row carries amount, completion and the payment detail

## Where to go next

- [Create a recurring invoice](/recurring-invoices/createCompanyRecurringInvoice)
- [Update a recurring invoice](/recurring-invoices/patchCompanyRecurringInvoice)

---

Full OpenAPI spec: https://docs.beel.es/api/openapi