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

Create a recurring invoice from an existing invoice

Scopeinvoices:write

Deprecated. Use POST /v1/companies/{company_id}/recurring-invoices/derivations, which creates the same template. The source invoice travels in the body as from_invoice_id, not in the path.

Creates a recurring invoice template taking its lines, recipient and configuration from an existing invoice.

POST
/v1/invoices/{invoice_id}/create-recurring

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

invoice_idstring
Formatuuid

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

namestring
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 silently creating a monthly template. Omitted, MONTHLY applies.

Value in"MONTHLY"
day_of_monthinteger
Range1 <= value <= 31
start_datestring

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
end_date?string|null
Formatdate
verifactu_enabled?boolean

Whether the invoices this template generates enter VeriFactu.

Omitting it inherits the value from the source invoice: pointing at one of your VeriFactu invoices and asking for it every month keeps VeriFactu. Send true or false explicitly to override that inheritance.

send_automatically?boolean
Defaultfalse
email_configuration?|null

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/create-recurring" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "day_of_month": 1,    "start_date": "2019-08-24"  }'
{
  "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"
  }
}

Create a recurring invoice POST

**Deprecated.** Use `POST /v1/companies/{company_id}/recurring-invoices`, which behaves identically. Creates a recurring invoice template: 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, and the resolved value is frozen into the template at creation time.

Get a recurring invoice GET

**Deprecated.** Use `GET /v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}`, which behaves identically. Retrieves the full details of a recurring invoice template, including its schedule, template lines and next generation date.