RecurringInvoices

Create a recurring invoice

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: frequency is how often it generates — every 1 (MONTHLY), 3 (QUARTERLY) or 12 (YEARLY) months — on day_of_month, from start_date until end_date if one is given. Omitted, MONTHLY applies.
  • The cadence governs the step, not the first invoice: the first occurrence is the first day_of_month on or after start_date, found one month at a time whatever the cadence; the cadence takes over from there. A YEARLY template starting 15 February with day_of_month 10 first invoices on 10 March, then every 10 March after that — it does not wait a year.
  • start_date in the past: accepted and stored as sent, but it never anchors generation backwards. next_generation becomes the first date of the template's own calendar on or after today (today included) — the grid of day_of_month dates anchored at start_date, one every frequency — so on a quarterly or yearly template it can land months from now, not this month. The missed periods are not generated. If today's period was already invoiced in the system you are migrating from, send a start_date of tomorrow (or of the next period) so it is not invoiced twice.
  • draft_in_advance: whether the invoice is created as a draft for review before it is emitted. The window is fixed at 5 days, and both options emit on the scheduled day. Generating manually a period whose scheduled date is today or earlier emits it on the spot. Omitted, no review draft is prepared. It supersedes the deprecated preview_days.
  • VeriFactu: the template does not carry it. Whether each generated invoice is registered with AEAT is decided when that invoice is issued, against the company's regime at that moment.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

post/v1/recurring-invoices

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/recurring-invoices
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses 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 for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

namestring required
frequency'MONTHLY' | 'QUARTERLY' | 'YEARLY'

Generation cadence: MONTHLY every month, QUARTERLY every 3 months, YEARLY every 12 months. Omitted, MONTHLY applies.

It governs the step from the first invoice onwards, not where that first one lands: the first occurrence is the first day_of_month on or after start_date, found one month at a time whatever the cadence. A yearly template starting 15 February with day_of_month 10 first invoices on 10 March, then every 10 March after that — it does not wait a year.

day_of_monthinteger required

Day of the month the invoices are issued. A month that does not have that day falls back to its last day: a template on 31 issues on 28 February (29 in a leap year) and on 30 April. So 31 is how you ask for the last day of the month it generates in — there is no separate flag for it, and the accepted range stays 1–31.

The adjustment does not stick and the schedule does not drift: every generation is recalculated from the day_of_month you sent, never from the date it was adjusted to (31 Jan → 28 Feb → 31 Mar).

start_datestring date required

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 becomes the first date of the template's own calendar on or after today (today included): the grid of day_of_month dates anchored at start_date, one every frequency. On a quarterly or yearly template that can be months from now, not this month. Invoices are never back-dated, so the missed periods are not generated. If today's period was already invoiced in the system you are migrating from, send a start_date of tomorrow (or of the next period) so it is not invoiced twice.

draft_in_advanceboolean

Whether the template prepares a draft for review before emitting. The window is fixed at 5 days and both options emit on the scheduled day. Omitted, the template is created without the review draft.

preview_daysinteger

Deprecated. Superseded by draft_in_advance, because the review window is no longer a number you pick: it is fixed at 5 days. Still accepted so nothing breaks — any value greater than 0 means the same as draft_in_advance: true, and 0 the same as false. When both are sent, draft_in_advance wins. It will be removed in a future version.

end_datestring date nullable
series_idstring uuid required
invoice_type'STANDARD' | 'SIMPLIFIED' required

Type of the invoices a recurring template generates: STANDARD for an identified recipient, SIMPLIFIED for a recipient that is not identified.

max_invoicesinteger nullable

Total number of invoices this template will generate before ending on its own, between 2 and 600. Leave it out (or send null) for a recurrence that is not capped by number.

A recurrence ends in ONE way: open-ended, on end_date, or after max_invoices. Sending both end_date and max_invoices with a value is rejected with RECURRING_END_MODE_CONFLICT, and so is a max_invoices that lands on a template that already has an end_date: the conflict is judged on the RESULTING state, not on the body. To switch modes, say both things in the same call — the new field with a value and the old one as null. Nothing is cleared silently.

The cap counts invoices GENERATED, not calendar turns: a skip does not spend it. The range is not enforced by this schema on purpose, so the rejection carries its own code and its own message: below 2 you do not want a recurrence but a scheduled invoice (PUT /v1/companies/{company_id}/invoices/{invoice_id}/schedule), which also issues it on an exact date.

customer_idstring uuid nullable
payment_method'NONE' | 'BANK_TRANSFER' | 'CARD' | 'CASH' | 'CHECK' | 'DIRECT_DEBIT' | 'BIZUM' | 'OTHER'

Payment method shown on invoices and recurring invoices.

  • NONE: no payment information is shown.
  • BANK_TRANSFER: bank transfer to the IBAN of the payment details; the only method that requires an IBAN.
  • CARD: card payment.
  • CASH: cash payment.
  • CHECK: payment by cheque.
  • DIRECT_DEBIT: direct debit from the customer's bank account.
  • BIZUM: payment through Bizum.
  • OTHER: any other method.
payment_ibanstring nullable
payment_swiftstring nullable
payment_term_daysinteger nullable
notesstring nullable
send_automaticallyboolean

Example request

{
  "max_invoices": 6,
  "lines": [
    {
      "unit_price": 50,
      "total_excluding_tax": 1,
      "total_including_tax": 100,
      "exemption_reason": "EXENTA_ART_20"
    }
  ],
  "payment_method": "BANK_TRANSFER",
  "custom_fields": [
    {
      "key": "project",
      "value": "Corporate website"
    }
  ],
  "email_configuration": {
    "recipients": [
      "user@example.com"
    ],
    "cc": [
      "user@example.com"
    ]
  }
}

Response

Recurring invoice created successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "draft_in_advance": true,
    "status": "ACTIVE",
    "pause": {
      "reason": "GENERATION_FAILURE",
      "blocker": "NIF_NOT_REGISTERED"
    },
    "lines": [
      {
        "pricing_mode": "UNIT_PRICE",
        "total_excluding_tax": 1,
        "total_including_tax": 100,
        "exemption_reason": "EXENTA_ART_20"
      }
    ],
    "amount": 106,
    "custom_fields": [
      {
        "key": "project",
        "label": "Project",
        "value": "Corporate website"
      }
    ],
    "max_invoices": 6,
    "last_generated_scheduled_date": "2026-05-01"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.