Get the generation history of a recurring invoice
Scopeinvoices:readReturns every entry in this schedule's history, newest first: the invoices it generated
and, just as important, the periods it did not — a failed unattended run, a slot a user
skipped, or the schedule being paused. Each entry carries its type, the origin of who
asked for it, a translated reason when there is one, and requested_by for a skip. That is
what lets you answer "why is there no invoice for March?" without reading logs.
Only GENERATED entries have an invoice_id; for the rest it is null.
Paginated with the usual page/limit, and the usual defaults: without them you get
the 20 most recent entries, not the whole history — which grows with every cycle the
template runs. Read data.pagination to walk the rest.
The deprecated flat alias GET /v1/recurring-invoices/{recurring_invoice_id}/history does
not paginate and returns only generated invoices: it is frozen as it shipped until
its Sunset date. Only this route returns every entry type.
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
Path Parameters
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidUnique identifier (UUID) of the recurring invoice template, as returned when it is created or listed. A template of another company answers 404 with RECURRING_NOT_FOUND, exactly like one that does not exist.
uuidQuery Parameters
Page number, starting at 1. The response echoes it back as pagination.current_page.
11 <= valueHow many items to return per page. The response echoes it back as pagination.items_per_page.
201 <= value <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/recurring-invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"{
"success": true,
"data": {
"history": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "GENERATED",
"invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
"origin": "UNATTENDED",
"reason": "string",
"requested_by": "cda0f200-65cd-4343-aedd-9c936b908826",
"requested_by_name": "string",
"generated_at": "2019-08-24T14:15:22Z",
"scheduled_date": "2019-08-24",
"invoice_number": "string",
"total": 0,
"status": "SCHEDULED"
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"total_items": 87,
"items_per_page": 20,
"has_next": true,
"has_previous": true
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
"details": {
"field": "invoice_id",
"invalid_value": "deliveries",
"expected_format": "UUID"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "Invoice not found"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation constraint violation.",
"details": {
"limit": "must be greater than or equal to 1"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Get the next occurrence of a recurring invoice GET
Returns the invoice that would be produced by the next generation of this recurring template, computed from the current issuer, recipient and series data. Nothing is persisted and no numbering is consumed.
Create a recurring invoice (deprecated) POST
**Deprecated.** Use `POST /v1/companies/{company_id}/recurring-invoices`, which behaves identically. Creates a recurring invoice template: the invoice data it repeats (lines, recipient, series, payment) plus the recurrence that drives it. - **Cadence:** `frequency` is how often it generates — every 1 (`MONTHLY`), 3 (`QUARTERLY`) or 12 (`YEARLY`) months — on `day_of_month`, from `start_date` until `end_date` if one is given. Omitted, `MONTHLY` applies. - **The cadence governs the step, not the first invoice:** the first occurrence is the first `day_of_month` on or after `start_date`, found one month at a time whatever the cadence; the cadence takes over from there. A `YEARLY` template starting 15 February with `day_of_month` 10 first invoices on 10 March, then every 10 March after that — it does not wait a year. - **`start_date` in the past:** accepted and stored as sent, but it never anchors generation backwards. `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` — so on a quarterly or yearly template it can land months from now, not this month. The missed periods are not generated. 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. - **`draft_in_advance`:** whether the invoice is created as a draft for review before it is emitted. 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, no review draft is prepared. It supersedes the deprecated `preview_days`. - **VeriFactu:** the template does not carry it. Whether each generated invoice is registered with AEAT is decided when that invoice is issued, against the company's regime at that moment. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.