List recurring invoices
Scopeinvoices:readDeprecated. Use GET /v1/companies/{company_id}/recurring-invoices, which returns the
same list with the same filters.
Lists the recurring invoice templates of the authenticated user, with filters and pagination.
- Filters:
statusandcustomer_id, pluspageandlimitfor pagination. - Sorting:
sort_byandsort_order. The legacy aliasessortBy/sortOrderare still honoured here but are not carried over to the canonical route.
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
Query Parameters
Lifecycle state of a recurring invoice schedule.
"ACTIVE" | "PAUSED" | "COMPLETED"uuidPage 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 <= 100Field to sort by. Defaults to created_at when omitted.
This parameter was previously named sortBy. The old name is still accepted for
backwards compatibility (see sortBy below) and will be withdrawn in a future major
version — send sort_by.
"name" | "next_generation" | "status" | "created_at"Deprecated — former name of sort_by, still honoured so existing integrations keep
working. Ignored when sort_by is also present. Use sort_by.
"name" | "next_generation" | "status" | "created_at"Sort direction. Defaults to desc when omitted.
This parameter was previously named sortOrder. The old name is still accepted for
backwards compatibility (see sortOrder below) and will be withdrawn in a future major
version — send sort_order.
"asc" | "desc"Deprecated — former name of sort_order, still honoured so existing integrations
keep working. Ignored when sort_order is also present. Use sort_order.
"asc" | "desc"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/recurring-invoices"{
"success": true,
"data": {
"recurring_invoices": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"frequency": "MONTHLY",
"day_of_month": 0,
"start_date": "2019-08-24",
"end_date": "2019-08-24",
"next_generation": "2019-08-24",
"preview_days": 3,
"status": "ACTIVE",
"pause": {
"reason": "USER",
"since": "2019-08-24T14:15:22Z",
"blocker": "NIF_NOT_REGISTERED"
},
"series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c",
"series_code": "string",
"invoice_type": "STANDARD",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"recipient_fiscal_name": "string",
"recipient_nif": "string",
"lines": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"order": 0,
"description": "string",
"quantity": 0,
"unit": "string",
"unit_price": 0,
"discount_percentage": 0,
"tax_type": "string",
"vat_rate": 0,
"regime_key": "string",
"equivalence_surcharge_rate": 0,
"irpf_rate": 0,
"exemption_reason": "EXENTA_ART_20",
"exemption_reason_text": "string"
}
],
"payment_method": "string",
"notes": "string",
"verifactu_enabled": true,
"send_automatically": true,
"email_configuration": {
"recipients": [
"string"
],
"cc": [
"string"
],
"subject": "string",
"message": "string"
},
"generated_invoices": 0,
"last_generated_at": "2019-08-24T14:15:22Z",
"source_invoice_id": "0c7d5f47-8759-4ef4-82d5-705413539f77",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
],
"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": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
},
"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 a recurring invoice GET
**Deprecated.** Use `GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}`, which behaves identically. Retrieves the full details of a recurring invoice template, including its schedule, template lines and next generation date.
Preview the next invoice of a recurring template GET
**Deprecated.** Use `GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/next-occurrence`, which behaves identically. 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.