Create a recurring invoice

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.

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

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.

Status	Code	When
`400`	`INVALID_IDEMPOTENCY_KEY`	The key breaks the format rules above.
`409`	`IDEMPOTENCY_KEY_PROCESSING`	The first request is still in flight. Wait and retry with the same key.
`409`	`IDEMPOTENCY_KEY_MISMATCH`	The 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

preview_days?integer

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

Default0

Range0 <= value <= 30

end_date?string|null

Formatdate

series_idstring

Formatuuid

invoice_typestring

Value in"STANDARD" | "SIMPLIFIED"

customer_id?string|null

Formatuuid

lines

Items1 <= items

payment_method?string

payment_iban?string|null

payment_swift?string|null

payment_term_days?integer|null

notes?string|null

verifactu_enabled?boolean

Whether the invoices generated by this template carry VeriFactu information.

If omitted, the company's declared preference applies (the "apply VeriFactu by default" setting, apply_by_default). If the company has no VeriFactu configuration, it resolves to false. Send the field explicitly (true or false) to override the preference.

The resolved value is frozen into the template at creation time and is returned by the API: changing the company preference later does not alter templates that already exist. Edit the template to change it.

send_automatically?boolean

Defaultfalse

email_configuration?|null

Response Body

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/recurring-invoices" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "day_of_month": 1,
    "start_date": "2019-08-24",
    "series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c",
    "invoice_type": "STANDARD",
    "lines": [
      {
        "description": "string",
        "quantity": 0.01,
        "unit_price": 0,
        "vat_rate": 0
      }
    ]
  }'

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/recurring-invoices" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "day_of_month": 1,    "start_date": "2019-08-24",    "series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c",    "invoice_type": "STANDARD",    "lines": [      {        "description": "string",        "quantity": 0.01,        "unit_price": 0,        "vat_rate": 0      }    ]  }'

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

Create a recurring invoice

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json