NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Recurring Invoices

List recurring invoices

Scopeinvoices:read

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

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

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.

Formatuuid

Query Parameters

status?string

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

Value in"ACTIVE" | "PAUSED" | "COMPLETED"
customer_id?string

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

Formatuuid
pause_reason?string

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.

Value in"USER" | "DOWNGRADE" | "GENERATION_FAILURE"
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",
        "draft_in_advance": true,
        "status": "ACTIVE",
        "is_failing": false,
        "pause": {
          "reason": "GENERATION_FAILURE",
          "since": "2019-08-24T14:15:22Z",
          "blocker": "NIF_NOT_REGISTERED"
        },
        "completion": {
          "reason": "USER",
          "at": "2019-08-24T14:15:22Z"
        },
        "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",
        "recipient_alternative_id": {
          "type": "NIF_IVA",
          "number": "string",
          "country_code": "st"
        },
        "lines": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "order": 0,
            "description": "string",
            "quantity": 0,
            "unit": "string",
            "unit_price": 0,
            "pricing_mode": "UNIT_PRICE",
            "total_excluding_tax": 1,
            "total_including_tax": 100,
            "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"
          }
        ],
        "amount": 106,
        "payment_method": "string",
        "payment_iban": "string",
        "payment_swift": "string",
        "payment_term_days": 0,
        "notes": "string",
        "send_automatically": true,
        "email_configuration": {
          "recipients": [
            "string"
          ],
          "cc": [
            "string"
          ],
          "subject": "string",
          "message": "string"
        },
        "generated_invoices": 0,
        "max_invoices": 6,
        "last_generated_at": "2019-08-24T14:15:22Z",
        "last_generated_scheduled_date": "2026-05-01",
        "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": "The invoice must have at least one line",
  "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 (deprecated) 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. - **Sent, paid or corrected invoices:** the successor operation documents when they can be voided (`issued_in_error`, `422 VOID_REQUIRES_ISSUED_IN_ERROR`, `422 INVOICE_HAS_LIVE_CORRECTIVES`, `422 TOTAL_CORRECTIVE_NOT_VOIDABLE`). - **PDF:** unchanged; the void is reported by the invoice's `status`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Get recurring invoice stats GET

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