# Recurring invoices (https://docs.getbeel.com/en/api/recurring-invoices)

Repeat an invoice every month, quarter or year, optionally sending it to SDI.

A recurring invoice starts from an invoice you already have (the **template**): every month, quarter or year Getbeel creates a draft copy dated that day, with the next number and the same payment term (the due date moves by the same number of days). With `auto_send` the new invoice also goes to SDI. Scope `invoices:write` (reads `invoices:read`).

In the app: open an issued invoice and choose **Make recurring**; the list is under **Fatture emesse → Recurring invoices**, with pause and resume.

## Create [#create]

```bash
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "invoice_id": "fe_…", "interval": "monthly", "auto_send": false }'
```

- `interval`: `monthly`, `quarterly` or `yearly`.
- `start_date` (optional, today or later): the date of the first new invoice. By default it is the first date after today in the series `invoice_date` + n × interval. A schedule on the 31st moves to the 28th after February (the day of the stored next date is kept).
- `auto_send`: send every new invoice to SDI. With a live key that is a real transmission; with a test key it goes to the sandbox. Proformas are never sent.

One schedule per invoice (`409 recurring_invoice_exists`). An invoice that cannot be copied (invalid data) answers `422 invoice_not_copyable`.

## How it runs [#how-it-runs]

Every morning Getbeel creates the invoices of the schedules that reached `next_date` and moves `next_date` to the next period. Live invoices follow the same rules as in the app: they need the SDI add-on and quota. When creation fails (for example the quota is used up) `last_error` says why and Getbeel tries again the next day; `last_invoice_id` is the latest invoice created.

Test keys see and create only sandbox schedules, live keys only real ones.

## Manage [#manage]

```bash
# list
curl https://www.getbeel.com/api/v1/recurring-invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# pause and resume
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/pause \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
curl -X POST https://www.getbeel.com/api/v1/recurring-invoices/$ID/resume \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# change
curl -X PATCH https://www.getbeel.com/api/v1/recurring-invoices/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval": "quarterly", "next_date": "2027-01-01", "auto_send": true }'

# delete (invoices already created stay)
curl -X DELETE https://www.getbeel.com/api/v1/recurring-invoices/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

On resume, a `next_date` already past jumps to the next period: no catch-up invoices.

## With an AI assistant [#with-an-ai-assistant]

The MCP tool `create_recurring_invoice` creates the schedule after confirming the interval and date with you; it sets `auto_send` only when you ask for it.
