RecurringInvoices

List recurring invoices

Deprecated. 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: status and customer_id, plus page and limit for pagination.
  • Sorting: sort_by and sort_order. The legacy aliases sortBy/sortOrder are still honoured here but are not carried over to the canonical route.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

get/v1/recurring-invoices

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/recurring-invoices
  • Auth: HTTP bearer

Query parameters

status'ACTIVE' | 'PAUSED' | 'COMPLETED'

Lifecycle state of a recurring invoice schedule.

  • ACTIVE: invoices are generated on schedule.
  • PAUSED: automatic generation is stopped and the schedule is kept; pause says who stopped it. It can be resumed.
  • COMPLETED: the schedule has ended for good and generates nothing more; completion says why. Terminal: it cannot be resumed or paused.
Example:ACTIVE
customer_idstring uuid
pageinteger

Page number, starting at 1. The response echoes it back as pagination.current_page.

limitinteger

How many items to return per page. The response echoes it back as pagination.items_per_page.

sort_by'name' | 'next_generation' | 'status' | 'created_at'

Field to sort by: name the template name, next_generation the next scheduled generation date, status the lifecycle state, created_at the creation instant.

next_generation orders by the schedule stored on the template, which is not always the date the response publishes: a template that carries null — COMPLETED, or PAUSED with a date already behind — is still ordered by the date it keeps. The ordering is stable and the same for two requests of the same page; it does not depend on today's date.

Field 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.

sortBy'name' | 'next_generation' | 'status' | 'created_at'

Field to sort by: name the template name, next_generation the next scheduled generation date, status the lifecycle state, created_at the creation instant.

next_generation orders by the schedule stored on the template, which is not always the date the response publishes: a template that carries null — COMPLETED, or PAUSED with a date already behind — is still ordered by the date it keeps. The ordering is stable and the same for two requests of the same page; it does not depend on today's date.

Deprecated — former name of sort_by, still honoured so existing integrations keep working. Ignored when sort_by is also present. Use sort_by.

sort_order'asc' | 'desc'

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.

sortOrder'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.

Response

Recurring invoices list retrieved successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "recurring_invoices": [
      {
        "draft_in_advance": true,
        "status": "ACTIVE",
        "pause": {
          "reason": "GENERATION_FAILURE",
          "blocker": "NIF_NOT_REGISTERED"
        },
        "lines": [
          {
            "pricing_mode": "UNIT_PRICE",
            "total_excluding_tax": 1,
            "total_including_tax": 100,
            "exemption_reason": "EXENTA_ART_20"
          }
        ],
        "amount": 106,
        "custom_fields": [
          {
            "key": "project",
            "label": "Project",
            "value": "Corporate website"
          }
        ],
        "max_invoices": 6,
        "last_generated_scheduled_date": "2026-05-01"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.