CompanyRecurringInvoices
Generate an invoice now from a recurring template
Runs the generation of this recurring template immediately, out of its schedule. It is a fiscal act: the generated invoice consumes numbering from the series of the template and, when the template says so, is issued and sent.
- It brings the upcoming occurrence forward, it does not add one: the call consumes the period that was pending, so the invoice is created now and next_generation advances one period. Generating manually, skipping and letting the schedule run each consume exactly one occurrence, so a monthly template still produces twelve invoices a year however you mix the three.
- next_generation in the response: the template's next date after this call consumed the pending occurrence, or null when the advance took the template past its end_date and its status is now COMPLETED.
- Templates with draft_in_advance: when the pending period's scheduled date is today or earlier, its review window has passed and the invoice is issued on the spot, dated today. When it is still ahead, the call creates the review draft with the scheduled date, and it is issued on that day.
- An extra invoice outside the calendar: do not use this endpoint. Create a normal invoice, or derive a draft from one the template already generated with POST /v1/companies/{company_id}/invoices/derivations. Either way the schedule stays where it was.
- Custom fields: the invoice copies those of the template, each with the label the field has now. A field archived since the template was saved is left out; it does not make the generation fail.
post/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/generate
Request
- Base URL: https://app.beel.es/api
- URL: https://app.beel.es/api/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/generate
- Auth: HTTP bearer
Headers
Idempotency-Keystring
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits, _ and - (max 255 chars)
- Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
- A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
| 409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
| 409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
Response
Invoice generated successfully
Example response
{
"success": true,
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.