NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Recurring Invoices

List recurring invoices

Scopeinvoices:read

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

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

Authorization

AuthorizationBearer <token>

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

company_idstring

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.

Formatuuid

Query Parameters

status?string

Lifecycle state of a recurring invoice schedule.

Value in"ACTIVE" | "PAUSED" | "COMPLETED"
customer_id?string
Formatuuid
page?integer

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

Default1
Range1 <= value
limit?integer

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

Default20
Range1 <= value <= 100
sort_by?string

Field to sort by. Defaults to created_at when omitted.

Value in"name" | "next_generation" | "status" | "created_at"
sort_order?string

Sort direction. Defaults to desc when omitted.

Value in"asc" | "desc"

Response Body

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"
{
  "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": "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": "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"
  }
}

Void an invoice POST

Voids an issued invoice, moving it to `VOIDED`. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/{invoice_id}/void`, which behaves identically. - **VeriFactu:** when it is enabled for the invoice, the cancellation is submitted to the AEAT. - **`reason`:** required in the body. `void_date` is optional.

Create a recurring invoice POST

Creates a recurring invoice template under this company (NIF): the invoice data it repeats (lines, recipient, series, payment) plus the recurrence that drives it. - **Cadence:** generation runs monthly on `day_of_month`, from `start_date` until `end_date` if one is given. `frequency` only accepts `MONTHLY`. - **`start_date` in the past:** accepted and stored as sent, but it never anchors generation backwards. `next_generation` moves to the first upcoming `day_of_month`, and the missed periods are not generated. - **`preview_days`:** how many days before the emission date the invoice is created as a draft for review. `0`, the default, means immediate emission. - **VeriFactu:** omitting `verifactu_enabled` applies the company's declared preference (`apply_by_default`, resolving to `false` when the company has no VeriFactu configuration). The resolved value is frozen into the template at creation time, so changing that preference later does not alter templates that already exist.