CompanyRecurringInvoices

List recurring invoices

Lists the recurring invoice templates of this company, with filters and pagination. Only the templates of the company in the path are returned.

get/v1/companies/{company_id}/recurring-invoices

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/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

Keeps only the schedules in this lifecycle state. Omitted, every state is listed.

customer_idstring uuid

Keeps only the schedules that invoice this customer of the company.

pause_reason'USER' | 'DOWNGRADE' | 'GENERATION_FAILURE'

Who stopped the schedule. USER a person did, from the API or the dashboard; DOWNGRADE the account lost the recurring-invoices feature; GENERATION_FAILURE an unattended run failed with something waiting will not fix — that one carries a blocker.

Example:GENERATION_FAILURE

Keeps only the schedules stopped for this reason — the same value the response returns in pause.reason. A single value; repeating the parameter is rejected.

It combines with status as an AND, with no special case: status=ACTIVE together with any pause_reason answers 200 with an empty list, because an active schedule has no pause to have a reason. Sending it alone already implies PAUSED, since that is the only state that records one.

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.

sort_order'asc' | 'desc'

Sort direction. Defaults to desc when omitted.

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.