Update a recurring invoice (deprecated)

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Template name. Cannot be cleared.

Generation cadence: MONTHLY every month, QUARTERLY every 3 months, YEARLY every 12 months. Omitted, the current one is kept — it is never reset to MONTHLY.

Changing it reschedules the template. The next generation is recalculated on the new grid — the day_of_month dates anchored at start_date, one every cadence — so it can land months later than the one you saw before the call. If the template has already issued invoices, the landing respects that: it is never a period that was already billed, and never before today either — the first point of the new grid strictly after the last invoiced one. It also discards a pending skip: the skipped period only existed as a point of the old grid, and that grid is gone. Send the same cadence and nothing is rescheduled.

Day of the month the invoices are issued. Moves the next generation immediately, on an ACTIVE template and on a PAUSED one alike: the response to this very call already carries the new next_generation. On a paused template the new day rules from the edit, not from the day you resume — resuming keeps the date this call left, so editing the day of a paused schedule is never ignored for a round.

A month that does not have that day falls back to its last day: a template on 31 issues on 28 February (29 in a leap year) and on 30 April. So 31 is how you ask for the last day of the month it generates in — there is no separate flag for it, and the accepted range stays 1–31.

The adjustment does not stick and the schedule does not drift: every generation is recalculated from the day_of_month you sent, never from the date it was adjusted to (31 Jan → 28 Feb → 31 Mar).

First issue date. Only changeable while the template has not generated any invoice yet: once it has issued, a different date is rejected with a 422 RECURRING_START_DATE_NOT_EDITABLE. Sending the value it already has is a no-op and succeeds, so a read-modify-write cycle never has to strip the field out of the body.

A past date is accepted and stored as sent, but it never anchors generation in the past: next_generation becomes the first date of the template's own calendar on or after today (today included) — the grid of day_of_month dates anchored at start_date, one every frequency — which on a quarterly or yearly template can be months from now. Creating and updating apply the same rule. If today's period was already invoiced in the system you are migrating from, send a start_date of tomorrow (or of the next period) so it is not invoiced twice.

Whether the template prepares a draft for review before emitting. The window is fixed at 5 days and both options emit on the scheduled day. Generating manually a period whose scheduled date is today or earlier emits it on the spot. Omitted, the current value is kept.

Deprecated. Superseded by draft_in_advance. Any value greater than 0 means the same as draft_in_advance: true, and 0 the same as false. When both are sent, draft_in_advance wins. It will be removed in a future version.

Date the recurrence stops. Send null to make it open-ended.

Total number of invoices this template will generate before ending on its own, between 2 and 600. Send null to stop capping the recurrence by number.

Editing it MOVES THE GOAL, it does not add turns: above the invoices already generated the template stays active; exactly equal ends it in this very call (with completion.reason = MAX_INVOICES_REACHED); below it the call is rejected — issued invoices are fiscal facts, and someone typing a lower number is asking to stop now, which is what ending the recurrence is for.

A recurrence ends in ONE way, and the conflict is judged on the RESULTING state, not on the body: sending max_invoices to a template that already has an end_date is rejected with RECURRING_END_MODE_CONFLICT even though the body only mentions one of them. Switching mode is a single call that says both things — the new field with a value and the old one as null. Nothing is cleared silently.

Series the generated invoices are numbered in. Cannot be cleared.

Recipient of the generated invoices. Send null to leave the template without a recipient; omit it to keep the current one.

Template lines, replaced as a whole (they are not patched line by line). Omit them to keep the current ones — a template with no lines invoices nothing, so an empty array is rejected.

Notes printed on the generated invoices. Send null to clear them.