RecurringInvoices

Replace a recurring invoice

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.

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

put/v1/recurring-invoices/{recurring_invoice_id}

Request

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

Path parameters

recurring_invoice_idstring uuid required

Unique identifier (UUID) of the recurring invoice template, as returned when it is created or listed. A template of another company answers 404 with RECURRING_NOT_FOUND, exactly like one that does not exist.

Request body

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

Generation cadence: MONTHLY every month, QUARTERLY every 3 months, YEARLY every 12 months. Omitted, the current one is kept — it is never reset to MONTHLY.

Changing it reschedules the template. The next generation is recalculated on the new grid — the day_of_month dates anchored at start_date, one every cadence — so it can land months later than the one you saw before the call. If the template has already issued invoices, the landing respects that: it is never a period that was already billed, and never before today either — the first point of the new grid strictly after the last invoiced one. It also discards a pending skip: the skipped period only existed as a point of the old grid, and that grid is gone. Send the same cadence and nothing is rescheduled.

day_of_monthinteger

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

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.

Once the template has issued, only a different date is rejected with a 422 RECURRING_START_DATE_NOT_EDITABLE. Resending the value it already has is a no-op, so this request can keep sending the template complete, as it asks above.

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. Generating manually a period whose scheduled date is today or earlier emits it on the spot. Omitted, the current value is kept.

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
max_invoicesinteger nullable

Total number of invoices this template will generate before ending on its own, between 2 and 600. Like end_date, it is cleared when you leave it out: this is a replacement.

A recurrence ends in ONE way: open-ended, on end_date, or after max_invoices. Sending both with a value is rejected with RECURRING_END_MODE_CONFLICT. 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).

Lowering it below the invoices already generated is rejected: issued invoices are fiscal facts and are not undone by moving the cap. Setting it exactly to the number already generated is accepted and ends the template in that same call.

series_idstring uuid
invoice_type'STANDARD' | 'SIMPLIFIED'

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

customer_idstring uuid nullable

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

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",
  "email_configuration": {
    "recipients": [
      "user@example.com"
    ],
    "cc": [
      "user@example.com"
    ]
  }
}

Response

Recurring invoice updated 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.