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

Replace a recurring invoice

Scopeinvoices:write

Deprecated. The canonical form has a single update verb, PATCH /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}, which is not a drop-in replacement: it changes only the fields present in the body. To reproduce a total replacement, send every field and pass null in the ones you want cleared.

Replaces the schedule, template lines and recipient of a recurring invoice with the body you send. Only allowed while the template is active or paused.

  • Not a partial update: leaving out end_date, payment_method (with its payment_iban, payment_swift and payment_term_days), notes or email_configuration clears them.
  • lines: replaced as a whole. Omitting them or sending null keeps the current ones, and an empty array is rejected.
  • verifactu_enabled: the exception to the rule — omitting it leaves the current value untouched, it is never read as "turn it off". Send false explicitly to disable VeriFactu.
PUT
/v1/recurring-invoices/{recurring_invoice_id}

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

recurring_invoice_idstring
Formatuuid

Request Body

name?string
Lengthlength <= 255
frequency?string

Generation cadence. Only MONTHLY is supported today; the field exists in the request so an unsupported cadence is rejected instead of being silently ignored.

Value in"MONTHLY"
day_of_month?integer
Range1 <= value <= 31
start_date?string

Date the subscription started. A past date is accepted and stored as sent — useful when migrating subscriptions from another system — but it never anchors generation in the past: next_generation moves to the first upcoming day_of_month. Invoices are never back-dated, so the missed periods are not generated.

Formatdate
preview_days?integer

Days before emission date to create a draft for review. 0 means immediate emission.

Range0 <= value <= 30
end_date?string|null
Formatdate
series_id?string
Formatuuid
customer_id?string|null

Recipient of the generated invoices. Send null to leave the template without a recipient; omit it to keep the current one.

Formatuuid
lines?|null

Template lines, replaced as a whole. Omit them (or send null) to keep the current ones — a template with no lines invoices nothing, so an empty array is rejected.

Items1 <= items
payment_method?string
Value in"NONE" | "BANK_TRANSFER" | "CARD" | "CASH" | "CHECK" | "DIRECT_DEBIT" | "BIZUM" | "OTHER"
payment_iban?string|null
payment_swift?string|null
payment_term_days?integer|null
notes?string|null
verifactu_enabled?boolean

Whether the invoices this template generates enter VeriFactu.

Omitting it leaves the current value untouched — it is never read as "turn it off". Send false explicitly to disable VeriFactu, true to enable it.

send_automatically?boolean
email_configuration?|null

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/recurring-invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "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"
  },
  "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Get the generation history of a recurring invoice GET

**Deprecated.** Use `GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/history`, which behaves identically. Returns the invoices previously generated from this recurring template, including their status and generation dates.

Update a recurring invoice PATCH

**Deprecated.** Use `PATCH /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}`, which behaves identically. Updates only the fields present in the body, leaving every other field of the recurring invoice template as it is. - **Omitted vs `null`:** an omitted field keeps its current value; a field sent as `null` is cleared, and only where the request schema documents the field as nullable. - **`lines`:** replaced as a whole, not patched line by line. The recipient survives the change, and an empty array is rejected. - **`payment_method`:** replaced as a whole together with `payment_iban`, `payment_swift` and `payment_term_days` — send them in the same request or they are dropped. - **Schedule:** `day_of_month` and `start_date` stay put unless you send them; sending `day_of_month` moves the next generation. `start_date` is only editable while the template has not generated any invoice yet.