--- title: "Create a recurring invoice" method: POST path: "/v1/companies/{company_id}/recurring-invoices" tags: ["CompanyRecurringInvoices"] --- # Create a recurring invoice `POST /v1/companies/{company_id}/recurring-invoices` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/companies/{company_id}/recurring-invoices` - Auth: HTTP bearer Creates a recurring invoice template under this company: 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. - **`custom_fields`:** copied to every invoice the template generates. A field archived later is left out of the invoices generated from then on, and the template keeps generating. ## Headers - `Idempotency-Key` string ## Request body - CreateRecurringInvoiceRequest - `name` string, 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_month` integer, 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_date` string, 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_advance` boolean: 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_days` integer: **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_date` string, date, nullable - `series_id` string, 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_invoices` integer, 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_id` string, uuid, nullable - `lines` RecurringLineRequest[], required - `description` string, required - `quantity` number, required - `unit` string - `unit_price` number: Unit price before taxes. Supports up to 4 decimal places for micro-pricing (e.g. €0.0897/unit for labels, packaging); the generated invoices always round their amounts to 2 decimals. Mutually exclusive with `total_excluding_tax` and `total_including_tax`. The upper bound is the same one the invoice line declares, and so is the acceptance of `0` (a discount granted before or simultaneously with the sale, e.g. a free introductory month). A price outside the range is rejected with `422 VALIDATION_ERROR` and the offending field in `details`. Negative prices are NOT accepted, unlike an invoice line of a corrective invoice: a recurring template only issues `STANDARD` or `SIMPLIFIED` invoices, and a corrective is created through its own endpoint over an already issued invoice — never generated by a template. - `total_excluding_tax` number: Declared line total excluding taxes: this amount IS the taxable base, exactly, with no recalculation. The stored `unit_price` becomes derived and informational (`total / quantity`, 4 decimals). Mutually exclusive with `unit_price` and `total_including_tax`. Negative totals are NOT accepted, for the same reason `unit_price` does not accept negative prices: a template only issues `STANDARD` or `SIMPLIFIED` invoices, and only a corrective invoice — created through its own endpoint over an already issued invoice — carries a negative amount. A total outside the range is rejected with `422 VALIDATION_ERROR` and the offending field in `details`. The upper bound is the same one `POST /v1/invoices` declares for a line total: a template is a promise to issue an invoice, and it cannot accept less than the invoice it will generate does. The derived `unit_price` (`total / quantity`) can still exceed the `maximum` this contract accepts for `unit_price` itself — what actually bounds it then is the domain's price ceiling, not this field's contract. - `total_including_tax` number: Declared line total including taxes — what the customer pays. The engine works the breakdown backwards so that taxable base + VAT + equivalence surcharge equals this amount exactly on every generated invoice. IRPF withholding is never part of the decomposition: it is a retention, not a price. Mutually exclusive with `unit_price` and `total_excluding_tax`. Negative totals are NOT accepted, same as `total_excluding_tax`. The upper bound is the same one `POST /v1/invoices` declares for a line total, for the same reason: the template cannot promise more than the invoice it generates could ever accept. The derived `unit_price` (`total / quantity`) can still exceed the `maximum` this contract accepts for `unit_price` itself — what actually bounds it then is the domain's price ceiling, not this field's contract. - `discount_percentage` number - `tax_type` string: Tax type. Omitted, `IVA` applies. - `vat_rate` number, required - `regime_key` string: VeriFactu regime key. Omitted, `01` (general regime) applies. - `equivalence_surcharge_rate` number, nullable - `irpf_rate` number, nullable - `exemption_reason` 'EXENTA_ART_20' | 'EXENTA_ART_21' | 'EXENTA_ART_22' | 'EXENTA_ART_24' | 'EXENTA_ART_25' | 'EXENTA_ART_26' | 'EXENTA_ART_140' | 'NO_SUJETA_ART_7_9' | 'NO_SUJETA_LOCALIZACION' | 'ISP_ART_84_2_A' | 'ISP_ART_84_2_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as. - `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1. - `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2. - `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3. - `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4. - `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5. - `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is `EXENTA_ART_25`. - `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1. - `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2. - `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2. - `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with `REVERSE_CHARGE_CASE_NOT_SUPPORTED`. - `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key` `04`). E6. - `REGIMEN_ART_129` (agriculture, livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods, art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`; declare the regime with `regime_key` instead. - `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6. - `exemption_reason_text` string, nullable: Custom exemption text. Only used when `exemption_reason` is `OTRO`. Same shape as an invoice line: the template declares WHY the operation carries no tax, and every invoice it generates inherits it. A 0% line without a reason is rejected on write — VeriFactu does not accept an exempt line with no explicit motive. - `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_iban` string, nullable - `payment_swift` string, nullable - `payment_term_days` integer, nullable - `notes` string, nullable - `custom_fields` InvoiceCustomFieldInput[]: Values for the company's custom fields that every generated invoice copies, at most one per `key`; a repeated `key` answers `422 VALIDATION_ERROR`. A `key` the company does not have answers `422 CUSTOM_FIELD_UNKNOWN`, and an archived field answers `409 CUSTOM_FIELD_ARCHIVED`; in both cases no template is created. Each value follows the same rules as on an invoice, with the template's `customer_id` as the customer. Omit it for a template without custom fields. They are informational: they are not part of the VeriFactu record sent to the AEAT, do not enter its hash and cannot express any mention the invoicing regulations require. - `key` string, required: Identifier of the custom field within the company, chosen when the field is created: lowercase letters, digits and `_`, up to 64 characters. It never changes. BeeL. gives it no meaning of its own. - `value` string, required: Text of the value. Leading and trailing spaces are removed; a value that is empty after that answers `422`. When an option of the field is equivalent (it matches ignoring case, accents and repeated spaces), the invoice stores the text of that option, archived options included. Otherwise the text is stored as sent and, when the invoice has a registered customer (`recipient.customer_id`), it is added as an option of that customer; with recipient data sent inline, no option is created. On a field with `suggest_values: false` the value is never compared with the options and never creates one: the invoice stores the text as sent, without the leading and trailing spaces. - `send_automatically` boolean - `email_configuration` RecurringEmailConfigRequest, nullable - `recipients` Email[] - `cc` Email[] - `subject` string, nullable - `message` string, nullable ## Response `201` Recurring invoice created successfully - object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it. - `success` boolean, required - `data` object, required: The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - `id` string, uuid - `name` string - `frequency` 'MONTHLY' | 'QUARTERLY' | 'YEARLY': Billing cadence of the template: `MONTHLY` every month, `QUARTERLY` every 3 months, `YEARLY` every 12 months. The day it falls on is `day_of_month`, the same anchor for all three. Set it when you create the template; a template created without it is `MONTHLY`. The cadence 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. A yearly template starting 15 February with `day_of_month` 10 first invoices on 10 March, then every 10 March after that. - `day_of_month` integer: Day of the month the invoices are issued, as it was requested: this is the anchor of the schedule, not the day the last invoice happened to land on. A month that does not have that day falls back to its last day, so `next_generation` can show a different day than this one — a template on `31` generates on 28 February (29 in a leap year) and on 30 April. The adjustment never sticks and the schedule does not drift: every generation is recalculated from this value, never from the date it was adjusted to (31 Jan → 28 Feb → 31 Mar). - `start_date` string, date - `end_date` string, date, nullable - `next_generation` string, date, nullable: Date the next invoice is generated — the one this template is actually going to honour. `null`, always present and never omitted, when there is none. There is none in two cases, and only in those two: - the template is `COMPLETED`: the date left on it is the one that ran past its end and triggered the closure, not a generation still to come; - the template is `PAUSED` and its date is strictly in the past: resuming does not go back to it — it reschedules from today onwards, so that date will never be invoiced. An `ACTIVE` template always carries its date, **including a date already in the past**: that is the occurrence about to be generated, and it is your only notice that an invoice is on its way. A `PAUSED` template whose date is still ahead — today counts as ahead — carries it too: it is exactly the date resuming would keep. The stored schedule is never rewritten by any of this. `next_generation` is what gets published, not what gets kept: resuming a long-paused template still reschedules from its own anchor, as it always did. - `draft_in_advance` boolean: Whether this template prepares a draft for review before emitting. The review window is fixed at 5 days: `true` creates the draft 5 days ahead, `false` goes straight to the emission. Either way the invoice is emitted on the scheduled `day_of_month` — what changes is only whether there is a draft to look at first. Generating manually (`POST .../generate`) a period whose scheduled date is today or earlier emits the invoice on the spot: its review window has already passed. - `status` 'ACTIVE' | 'PAUSED' | 'COMPLETED': Lifecycle state of a recurring invoice schedule. - `ACTIVE`: invoices are generated on schedule. - `PAUSED`: automatic generation is stopped and the schedule is kept; `pause` says who stopped it. It can be resumed. - `COMPLETED`: the schedule has ended for good and generates nothing more; `completion` says why. Terminal: it cannot be resumed or paused. - `is_failing` boolean: Whether this template is failing right now — from the FIRST failed unattended run, not the third. The warning email only goes out on every 3rd consecutive retryable failure, so `next_generation` not moving used to be the only clue before that; this field surfaces the same signal from the very first one. `true` when either an unattended run has failed at least once and the retry streak has not been cleared by a successful generation yet (even while `status` is still `ACTIVE`, before any email fires), or `status` is `PAUSED` with `pause.reason = GENERATION_FAILURE`. Derived on every read from data already stored — it is not a new column and nothing else changes because of it. - `pause` RecurringInvoicePause, nullable: Why this schedule is paused. Present while `status` is `PAUSED`; absent otherwise, and also absent for schedules paused before this was recorded. `PAUSED` covers three facts that are not interchangeable: someone paused it, a plan downgrade paused it, or an unattended generation failed with something waiting will not fix. A transient failure (network, timeout, tax authority downtime) does NOT pause the schedule — the next run retries it. - `reason` 'USER' | 'DOWNGRADE' | 'GENERATION_FAILURE': Who stopped the schedule. `USER` a person did, from the API or the dashboard; `DOWNGRADE` the account lost the recurring-invoices feature; `GENERATION_FAILURE` an unattended run failed with something waiting will not fix — that one carries a `blocker`. - `since` string, date-time - `blocker` string: What blocked the emission, using the same codes the emission error returns (the `blockers[]` of a 422 `EMISSION_NOT_READY`). Only for `GENERATION_FAILURE`, and it may be absent when the permanent failure was not a readiness one. Resuming is rejected while this blocker is still in effect. - `completion` RecurringInvoiceCompletion, nullable: Why this schedule ended. Present while `status` is `COMPLETED`; absent otherwise, and also absent for schedules completed before this was recorded — that cause is not known and is not invented. `COMPLETED` covers facts that are not interchangeable: the owner ended it, the calendar ran out, or the agreed number of invoices did. It stays a **single** terminal status and `status` keeps its three values: no business rule branches on the cause, and a new status value would break every exhaustive `switch`. New causes land in `reason`, so treat it as an open set. - `reason` 'USER' | 'END_DATE_REACHED' | 'MAX_INVOICES_REACHED': `USER` — someone completed it (`PUT .../status` to `COMPLETED`). `END_DATE_REACHED` — the next occurrence landed past `end_date`, so there was nothing left to generate. This includes automatic generation and the common close of generating, skipping and resuming. `MAX_INVOICES_REACHED` — the `max_invoices` cap ran out: the last agreed invoice was generated (or the cap was moved down to the number already generated). When a template exhausts its cap and its `end_date` on the very same turn this is the cause reported: the cap is the fact that just happened, the date is the calendar consequence that follows. - `at` string, date-time: Instant the schedule was closed. - `series_id` string, uuid - `series_code` string - `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_id` string, uuid, nullable - `recipient_fiscal_name` string, nullable - `recipient_nif` string, nullable: Spanish Tax ID of the recipient. Mutually exclusive with `recipient_alternative_id`: a recipient is identified by exactly one of the two, never both, and `null` when the other one carries the identifier (or when there is no recipient identified at all). - `recipient_alternative_id` object, nullable: Alternative identifier of the recipient (NIF-IVA, passport, etc.), same shape as the customer's own `alternative_id`. Mutually exclusive with `recipient_nif`: `null` when the recipient carries a Spanish `recipient_nif` instead, or when there is no recipient identified at all. - `type` 'NIF_IVA' | 'PASSPORT' | 'COUNTRY_ID' | 'RESIDENCE_CERTIFICATE' | 'OTHER_DOCUMENT' | 'NOT_REGISTERED' | '02' | '03' | '04' | '05' | '06' | '07', required: Identifier type. Use descriptive names: - **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure* - **PASSPORT**: Passport — *allowed for any country* - **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`* - **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`* - **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`* - **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`* **⚠️ DEPRECATED numeric codes** (will be removed in v2): 02, 03, 04, 05, 06, 07 — use the descriptive names above instead. - `number` string, required: Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix (e.g. `FR40303265045`); see the VeriFactu rules on the parent schema. - `country_code` string: ISO 3166-1 alpha-2 code of the country that issued the document. Required except for `PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed `type` values; see the VeriFactu rules on the parent schema. - `lines` InvoiceLineTemplateResponse[] - `id` string, uuid - `order` integer - `description` string - `quantity` number - `unit` string, nullable - `unit_price` number: Unit price of the template line. In both total-declared modes (`pricing_mode` other than `UNIT_PRICE`) this value is **derived and informational** (`total / quantity`, 4 decimals): re-multiplying it does not reproduce the declared total on large quantities. - `pricing_mode` 'UNIT_PRICE' | 'TOTAL_EXCLUDING_TAX' | 'TOTAL_INCLUDING_TAX': How the line amount was entered. - `UNIT_PRICE`: classic mode — the amount is derived from `unit_price` (`quantity × unit_price × (1 − discount / 100)`). - `TOTAL_EXCLUDING_TAX`: total-declared mode — `total_excluding_tax` is the exact taxable base and `unit_price` is derived and informational (`total / quantity`, 4 decimals). - `TOTAL_INCLUDING_TAX`: tax-inclusive total-declared mode — `total_including_tax` is what the customer paid (taxable base + VAT + equivalence surcharge) and the engine works the breakdown backwards so the rounded amounts add up to the declared total exactly. In both total-declared modes re-multiplying the derived `unit_price` does NOT reproduce the declared total on large quantities (1.00 € ÷ 300 units → 0.0033 × 300 = 0.99), which is precisely why the declared total is the source of truth. - `total_excluding_tax` number: Declared line total excluding taxes. Only present on lines with `pricing_mode = TOTAL_EXCLUDING_TAX`. It never includes taxes nor subtracts IRPF withholding. - `total_including_tax` number: Declared line total including taxes (taxable base + VAT + equivalence surcharge; IRPF withholding is never subtracted). Only present on lines with `pricing_mode = TOTAL_INCLUDING_TAX`. Every invoice this template generates reproduces it exactly. - `discount_percentage` number, nullable - `tax_type` string - `vat_rate` number - `regime_key` string - `equivalence_surcharge_rate` number, nullable - `irpf_rate` number, nullable - `exemption_reason` 'EXENTA_ART_20' | 'EXENTA_ART_21' | 'EXENTA_ART_22' | 'EXENTA_ART_24' | 'EXENTA_ART_25' | 'EXENTA_ART_26' | 'EXENTA_ART_140' | 'NO_SUJETA_ART_7_9' | 'NO_SUJETA_LOCALIZACION' | 'ISP_ART_84_2_A' | 'ISP_ART_84_2_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as. - `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1. - `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2. - `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3. - `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4. - `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5. - `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is `EXENTA_ART_25`. - `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1. - `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2. - `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2. - `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with `REVERSE_CHARGE_CASE_NOT_SUPPORTED`. - `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key` `04`). E6. - `REGIMEN_ART_129` (agriculture, livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods, art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`; declare the regime with `regime_key` instead. - `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6. - `exemption_reason_text` string, nullable: Custom exemption text. Only used when exemption_reason is OTRO. - `amount` number, nullable: What the customer will be asked to transfer on the next invoice this template generates: taxable base + VAT + equivalence surcharge − IRPF withholding + disbursements (`suplidos`). It is NOT the taxable base and NOT the total with VAT: the withholding is already subtracted. The same number the next occurrence publishes as `total_to_pay`, to the cent: both come from the template's own lines through the same line pipeline the real generation uses. It is computed on the fly and stored nowhere, so it always reflects the lines the template carries right now — and it is not sortable or filterable for that reason. `null` when the template's lines cannot be priced (no lines, or lines the engine rejects). The rest of the template is still returned. - `payment_method` string, nullable - `payment_iban` string, nullable: Full IBAN of the template's own payment method, mirrored from what was sent when it was set. `null` when the template has no payment method. - `payment_swift` string, nullable: SWIFT/BIC code of the template's own payment method. `null` when the template has no payment method, or when it has one without a SWIFT code. - `payment_term_days` integer, nullable: Payment term, in days, of the template's own payment method. `null` when the template has no payment method, or when it has one without a declared term. Each generated invoice is due on its issue date plus this term. When it is `null`, the company's default `payment_term_days` (tax configuration) applies, or 30 days if the company has none. - `notes` string, nullable - `custom_fields` InvoiceCustomField[], required: The company's custom fields saved on this template, each with the label and value it was saved with; an empty array when it carries none. Every invoice the template generates copies them. The generated invoice saves each field with the label it has at that moment; a field archived after the template was saved stays listed here, but the invoices generated from then on are created without it and the template keeps generating: it is not paused for that reason. They are informational: they are not part of the VeriFactu record sent to the AEAT and do not enter its hash. - `key` string, required: Identifier of the custom field within the company, chosen when the field is created: lowercase letters, digits and `_`, up to 64 characters. It never changes. BeeL. gives it no meaning of its own. - `label` string, required: Label of the field when the invoice was saved. - `value` string, required: Text stored on the invoice. It is the text the `custom_fields` filter of the invoice list compares. - `send_automatically` boolean - `email_configuration` RecurringEmailConfigResponse, nullable - `recipients` string[] - `cc` string[] - `subject` string, nullable - `message` string, nullable - `generated_invoices` integer - `max_invoices` integer, nullable: Total number of invoices agreed for this template, or absent when the recurrence is not capped by number. It is the TOTAL agreed, not what is left: "remaining" is `max_invoices - generated_invoices`, a derived reading with no field of its own — two counters of the same fact drift, and the day they do nobody knows which one is true. What counts against it are invoices GENERATED, not calendar turns: a skip does not spend cap because it produces no invoice, and a `generate now` does because it produces a real fiscal invoice. When the last one is generated the template is closed in the act, with `completion.reason = MAX_INVOICES_REACHED`. - `last_generated_at` string, date-time, nullable - `last_generated_scheduled_date` string, date, nullable: Calendar date of the latest period this template has already invoiced: the highest `scheduled_date` in its generation history. `null` when it has never generated an invoice. It is NOT the date of `last_generated_at`. That field is the instant the most recent invoice was created; this one is the calendar slot that invoice (or an earlier one) was issued for. They diverge on purpose: a `generate now` creates today an invoice for a future slot, and a re-anchored schedule can generate a slot out of order, so the latest invoice created is not necessarily the one with the latest slot. Skipping a period does not move it: a skip produces no invoice, so it consumes no slot. Deleting a generated invoice does not move it either, with one exception: deleting the draft of the latest generation releases that slot (the period becomes available to generate again, and `generated_invoices` goes down by one), so this date moves back to the previous generated slot, or to `null` if there is none. - `source_invoice_id` string, uuid, nullable - `created_at` string, date-time - `updated_at` string, date-time - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `400`: `INVALID_JSON_FORMAT` — the body is not valid JSON, or a property has the wrong type or format (a string where a number is expected, a date that does not parse, a malformed UUID, a boolean that is not `true`/`false`). The `details` object follows `FieldDeserializationError`: `field`, `invalid_value` and, where there is one, `expected_format` (or `allowed_values`, for a boolean). A property the operation does not declare is not a format error: it is ignored. A value outside an **enum**'s vocabulary is not answered here. The property is a well-formed string that names nothing the operation knows, so it is judged as content: `422` (`VALIDATION_ERROR`), with the same `FieldDeserializationError` shape in `details` (`field`, `invalid_value`, `allowed_values`). Other `error.code` values with this status: - `EXEMPTION_INCOMPATIBLE_WITH_REGIME` — the line's `exemption_reason` cannot be declared under its `regime_key` (e.g. E2/E3 with key `01`); change the key or the reason. - `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU` — `REGIMEN_ART_*` reasons are special regimes, not exemptions; declare the matching `regime_key` instead of an exemption reason. - `ISP_INCOMPATIBLE_WITH_SURCHARGE` — a reverse-charge line (`ISP_*`) cannot carry an equivalence surcharge; remove the surcharge or the reverse-charge reason. - `OSS_REGIME_INCOMPATIBLE_WITH_ISP` — regime key `17` (OSS/IOSS) cannot be combined with a reverse-charge `exemption_reason`; choose one. - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Your account does not own or manage this company, or does not hold the required access over it. A NIF that does not exist answers the same way. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`. - `404`: The `customer_id` referenced in the body does not exist. It never refers to the NIF in the path: a NIF you cannot reach answers `403`. Other `error.code` values with this status: - `INVOICE_SERIES_NOT_FOUND` — the `series_id` does not exist in this company and environment (a Test series is invisible from Live and vice versa). List the series and send an existing id, or omit it to use the default. - `409`: The request is well formed but collides with the state that is already there, told apart by `error.code`: - `CUSTOM_FIELD_ARCHIVED` — a `key` in `custom_fields` names a field the company has archived. Reactivate the field, or send `custom_fields` without it. No template is created. - `CONCURRENT_MODIFICATION` — another write changed the template first; read it again and retry. - `IDEMPOTENCY_KEY_PROCESSING` — the `Idempotency-Key` you sent is still in flight; retry after a moment. `IDEMPOTENCY_KEY_MISMATCH` — it was already used for a different body; use a new key. - `422`: Validation error. A line whose `exemption_reason` requires the recipient to carry a specific alternate identifier type (today, `EXENTA_ART_25` needs `NIF_IVA`) is rejected with `error.code` `EXEMPTION_REQUIRES_RECIPIENT_ID_TYPE` when the customer referenced by `customer_id` does not carry it. No template is created — the same rejection `POST /v1/companies/{company_id}/invoices` gives for the same case, brought forward to the write instead of every generated invoice bouncing at the AEAT. Also, from the template's payment and delivery settings: `payment_method` `BANK_TRANSFER` or `DIRECT_DEBIT` without `payment_iban` answers `IBAN_REQUIRED`; a `payment_term_days` outside 0–365 answers `PLAZO_DIAS_OUT_OF_RANGE`; and `send_automatically: true` with nobody to send to — no recipients in `email_configuration`, no `billing_emails` on the customer and no recipient email — answers `SIN_DESTINATARIO_RESOLUBLE`, since every generated invoice would fail to send. Separately: on a line priced by declared total (`total_excluding_tax` or `total_including_tax`) the unit price is not sent — it is derived as total ÷ quantity — so a quotient that does not fit the field storing it is rejected with `error.code` `LINE_UNIT_PRICE_OUT_OF_RANGE` and an `error.details` that follows `LineUnitPriceOutOfRangeDetails`: `field` names the offending line (`lines[0]`), not a `unit_price` you never sent, while `max` and `derived_unit_price` carry the limit and the quotient as JSON numbers, so they can be compared without parsing `error.message`. A `unit_price` you send with more than 4 decimal places is rejected with `error.code` `LINE_UNIT_PRICE_TOO_MANY_DECIMALS` instead of being rounded. Also: `frequency` and `end_date` can each be valid on their own and still be impossible together, when the window between `start_date` and `end_date` holds no occurrence at all — a `YEARLY` template covering a calendar year, created with the year already under way, is the everyday case. That is rejected with `error.code` `RECURRING_NO_OCCURRENCE_IN_WINDOW`, and its `error.details` hangs off `end_date`, the field you can move; the other lever is `frequency`. It is not the same as `RECURRING_END_DATE_BEFORE_START`, which says the *next* generation of a template that already had one falls past its end: this one says there is no first invoice, and never will be. Retrying does not help — widen `end_date` or shorten `frequency`. Also: `series_id` (explicit or resolved by default) numbering against a series that is inactive is rejected with `error.code` `SERIES_INACTIVE` — no template is created. Activate the series, or send a `series_id` for one that is already active. Other `error.code` values with this status: - `CUSTOM_FIELD_UNKNOWN` — a `key` in `custom_fields` is not a custom field of this company in this environment; create it with `PUT …/custom-fields/{key}` or fix the key. - `EXEMPTION_NOT_FOR_ISSUED_INVOICE` — `EXENTA_ART_26` exempts the buyer's intra-community acquisition, not a sale you invoice; use `EXENTA_ART_25` for the intra-community supply. - `EXEMPT_ZERO_RATE_REQUIRES_REASON` — a 0 % IVA or IPSI line is the exemption sentinel and needs an `exemption_reason`; add one or use a real rate. - `INVALID_IRPF` — the `irpf_rate` is not a withholding rate in force (see `IrpfPercentage`); send one of the published rates. - `INVALID_IVA_SURCHARGE_PAIR` — the equivalence surcharge does not match the line's VAT rate (21↔5.2, 10↔1.4, 5↔0.62, 4↔0.5); fix either rate. - `INVALID_PERCENTAGE` — the `percentage` is not a rate of that tax type (e.g. IVA 13); the message lists the valid rates. OSS key `17` accepts any EU rate. - `INVALID_REGIME_KEY_FOR_TAX_TYPE` — the `regime_key` does not exist for that tax type (e.g. `18` under IGIC); `details.allowed_values` lists the accepted keys. - `INVALID_SURCHARGE` — the `equivalence_surcharge_rate` is not an equivalence surcharge rate (see `EquivalenceSurchargePercentage`); send one of the published values. - `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER` — the issuer is a company (corporate income tax), which can only withhold 0, 19 or 24 %; use one of those. - `IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER` — the rate (e.g. 9.5 % Ceuta/Melilla) only applies to corporate issuers; an individual issuer must use a personal-income-tax rate. - `LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT` — a line with `total_excluding_tax` or `total_including_tax` cannot also send `discount_percentage`; the total already includes any discount. - `LINE_EXEMPTION_TEXT_REQUIRED` — `exemption_reason: OTRO` needs `exemption_reason_text` explaining the exemption; add it. - `LINE_EXEMPTION_WITH_TAX` — the line declares an `exemption_reason` but a non-zero rate; exempt or non-subject lines go at 0 %. - `LINE_NORMAL_DESCRIPTION_REQUIRED` — a `NORMAL` line has an empty or blank `description`; describe the invoiced concept. - `LINE_UNIT_PRICE_XOR_DECLARED_TOTAL` — each line must carry exactly one of `unit_price`, `total_excluding_tax` or `total_including_tax`; none or several were sent. - `NEGATIVE_TOTAL_REQUIRES_RECTIFICATIVE` — the lines add up to a negative total; only a corrective invoice can be negative. Correct the original with `POST …/corrective`. - `PAYMENT_DETAILS_REQUIRE_METHOD` — `payment_iban`, `payment_swift` or `payment_term_days` was sent without a `payment_method` (or with `NONE`); send the method with them. - `PERCENTAGE_OUT_OF_RANGE` — a percentage (discount, tax, surcharge or withholding) is below 0 or above 100. - `RECIPIENT_ID_REQUIRED` — a standard invoice needs an identified recipient: a `customer_id`, or inline data with `nif` or `alternative_id`. - `RECURRING_END_MODE_CONFLICT` — the resulting template would have both `end_date` and `max_invoices`. A recurrence ends one way: send the new field with a value and the other as `null` in the same call. - `RECURRING_MAX_INVOICES_ABOVE_MAXIMUM` — `max_invoices` is above 600. Send a lower cap, or `null` for a recurrence not capped by number. - `RECURRING_MAX_INVOICES_BELOW_MINIMUM` — `max_invoices` is below 2. For a single future invoice, schedule it instead with `PUT /v1/companies/{company_id}/invoices/{invoice_id}/schedule`. - `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED` — AEAT does not accept that `exemption_reason` (or its absence) with the line's `regime_key`; the message lists the reasons it admits. - `REGIME_KEY_NOT_SUPPORTED` — BeeL. cannot declare that `regime_key` to AEAT (e.g. `06`, `14`); use another key. - `REGIME_KEY_REQUIRES_RECIPIENT_NIF` — regime key `10` (collections on behalf of third parties) requires a recipient identified with a Spanish NIF. - `REGIME_KEY_REQUIRES_STANDARD_INVOICE` — the line's `regime_key` is only accepted on a standard (F1) invoice; change the invoice type or the key. - `REGIME_KEY_REQUIRES_VAT_RATE` — the line's `regime_key` only admits one VAT rate (named in the message); use that rate or an exemption reason. - `REGIME_REQUIRES_INCOMPATIBLE_EXEMPTION` — the line's `regime_key` requires one of a set of exemption reasons (e.g. `02` exports) and the line has none or another. - `REVERSE_CHARGE_CASE_NOT_SUPPORTED` — that reverse-charge case (e.g. `ISP_ART_84_2_G`, which needs a special series) is not supported; issue it outside BeeL. or use another reason. - `SIMPLIFICADA_FORBIDS_CROSS_BORDER` — a simplified invoice cannot document a cross-border operation (art. 25 exemption or not subject by place of supply); issue a standard invoice. - `SIMPLIFICADA_FORBIDS_IRPF` — a simplified invoice cannot carry IRPF withholding; remove `irpf_rate` or issue a standard invoice. - `SIMPLIFICADA_FORBIDS_ISP` — a simplified invoice cannot carry a reverse-charge (`ISP_*`) line; issue a standard invoice. - `SIMPLIFICADA_FORBIDS_SURCHARGE` — a simplified invoice cannot carry an equivalence surcharge; send `equivalence_surcharge_rate: 0` or issue a standard invoice. - `SURCHARGE_REQUIRES_REGIME` — an equivalence surcharge was sent with a `regime_key` other than `01`/`18` (e.g. `02`, `03`, `17`); only regime `18` admits it. - `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known. - `500`: Internal server error - `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry. --- [API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)