Get recurring invoice stats
Scopeinvoices:readHow many recurring schedules this company has alive, what they add up to per month, and how much invoicing is stopped because the unattended generation broke.
It is the whole company, and it takes no filters. It is an anchor, not a summary of whatever the list is showing: narrowing the list by customer or by status does not move these figures. Pagination does not apply either — the numbers cover every schedule of the company, not a page of them.
The two amounts are never added together. active.monthly_amount is a forecast of
what is going to be invoiced; stopped.monthly_amount is invoicing that should be
happening and is not. There is deliberately no grand total in the response.
The per-schedule figures behind them are the same ones
GET /v1/companies/{company_id}/recurring-invoices publishes as amount, so the rows
and this header cannot drift: adding the amount of every active row by hand gives
active.monthly_amount exactly, to the cent.
Filters of the list are rejected, not ignored: sending status, customer_id or any
other unknown parameter answers 400 naming it. Asking for a filtered header and getting
whole-company figures back with a 200 would be worse than being told no.
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.
uuidResponse Body
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/stats"{
"success": true,
"data": {
"active": {
"count": 7,
"monthly_amount": 2140,
"uncounted_count": 0
},
"stopped": {
"count": 7,
"monthly_amount": 2140,
"uncounted_count": 0
}
},
"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": "La factura debe tener al menos una línea",
"instance": "/v1/invoices/abc-123"
}{
"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"
}
}List recurring invoices GET
Lists the recurring invoice templates of this company, with filters and pagination. Only the templates of the company in the path are returned.
Create a recurring invoice POST
Creates a recurring invoice template under this company: 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 next date of the template's own calendar that is still ahead — 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. - **`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. 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.