Corrective invoices (R1–R5)

A corrective invoice (factura rectificativa) corrects a previously issued invoice. BeeL. exposes them through POST /v1/companies/{company_id}/invoices/{invoice_id}/corrective — the URL points to the original invoice, and the body describes the correction.

You decide two things:

• rectification_type — TOTAL (rectify everything still invoiced on the original) or PARTIAL (apply a delta)
• rectification_code — R1–R5 (the legal motive)

Plus a reason in free text (10–1,000 characters) describing the situation in human language. All three are required.

The corrective comes back with type: CORRECTIVE and rectified_invoice_id pointing at the original. It goes through VeriFactu exactly like any other invoice: same verifactu block, same states, same QR and the same verifactu.status.updated webhook.

The two axes

           PARTIAL  (one delta registro, easy bookkeeping)
        ┌────────────────────────────────────────────────┐
why →   │  R1   │  R2   │  R3   │  R4   │  R5  (F2 only) │
        ├────────────────────────────────────────────────┤
           TOTAL    (one registro replaces the original)

The original invoice's status changes after issuance:

• PARTIAL → original becomes RECTIFIED (can be corrected again — several partial correctives on the same original are fine)
• TOTAL → original becomes VOIDED (terminal, no further correctives)

A TOTAL rectifies what is still invoiced on the original: its lines and those of its live correctives (voided ones do not count), negated. After two partial correctives, a TOTAL takes back only what they left. If they already brought the invoice to zero, it answers 422 CORRECTIVE_NOTHING_LEFT_TO_RECTIFY.

A corrective whose total_to_pay is 0 — a recipient-data correction, for example — has nothing to refund or collect, so it is issued as PAID, with payment_date equal to issue_date.

What a TOTAL corrective does to the original

The original moves to VOIDED, but no cancellation record is sent to AEAT for it. The correction travels in the corrective's own registration — a tipo_rectificativa S record that references the original. So, on the original:

• its verifactu.submission_status keeps its registration's outcome (typically ACCEPTED) — it does not become VOIDED;
• its VeriFactu records show no VOID record.
• its PDF does not change: it stays the document that was delivered. The corrective has its own PDF.

That is the difference from the void endpoint, which does send a cancellation record. Both leave the invoice VOIDED; only one tells AEAT the invoice should not exist — and it is only for an invoice issued by mistake. An operation that did take place is corrected, not voided.

Pick the reason (R1–R5)

Deadline and circumstance_date

A corrective must be issued within four years from when the tax accrued — the original's operation_date, or its issue_date when it has none — or, for a cause of article 80 of the VAT Act (R1, R2, R3, R5), from when the circumstance took place. Send that date as circumstance_date (a discount granted later, an order cancelled, the insolvency order, the bad-debt claim); without it, the four years count from the operation date.

Scenario 1 — TOTAL cancellation (R1)

The operation was left without effect by agreement with the customer (an order cancelled before delivery, Art. 80 Dos LIVA). Don't send lines for a TOTAL: it rectifies everything still invoiced on the original. Sending them is rejected with RECTIFICATIVA_TOTAL_CON_LINEAS.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/corrective" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "TOTAL",
    "rectification_code": "R1",
    "reason": "Order cancelled by agreement with the customer before delivery: the operation is left without effect (Art. 80 Dos LIVA).",
    "circumstance_date": "2026-03-10",
    "notes": "Cancellation agreed with the customer on 10/03/2026. No amount pending collection."
  }'

The original becomes VOIDED; the corrective carries the matching tipo_rectificativa S to AEAT.

Scenario 2 — PARTIAL adjustment for bankruptcy (R2)

The customer was declared insolvent and has not paid the VAT charged; you reduce the unpaid part. Send the delta as a PARTIAL, with the date of the insolvency order as circumstance_date. R2 needs a recipient established in Spain, the Canary Islands, Ceuta or Melilla — or in another EU member state, for insolvency proceedings there — or it answers 422 CORRECTIVE_RECIPIENT_NOT_ESTABLISHED.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/corrective" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "PARTIAL",
    "rectification_code": "R2",
    "reason": "Customer declared insolvent by order of 10/02/2026 (Commercial Court No. 2 Madrid, case 123/2026): the unpaid part of the invoice is reduced under Art. 80 Tres LIVA.",
    "circumstance_date": "2026-02-10",
    "lines": [
      {
        "description": "Unpaid amount at the insolvency declaration",
        "quantity": -16,
        "unit": "hours",
        "unit_price": 37.5,
        "discount_percentage": 0,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        }
      }
    ],
    "notes": "Credit communicated to the insolvency administrator."
  }'

Lines carry negative quantity (or negative unit_price) to express the reduction. The original stays RECTIFIED.

A PARTIAL may raise any amount, but it may not take the taxable base of any rate below zero once the previous correctives are counted: that answers 422 CORRECTIVE_EXCEEDS_INVOICED_AMOUNT, with tax_group (for example IVA 21%) and max_reduction in error.details. And a PARTIAL whose lines only change the withholding answers 422 CORRECTIVE_WITHHOLDING_ONLY: a withholding that should not have been applied is not a cause for a corrective — void the invoice and issue a new one without it.

Scenario 3 — PARTIAL bad-debt write-off (R3)

Documented bad debt under Art. 80 Cuatro LIVA. Send a negative line for the uncollectible part, with the date of the claim as circumstance_date. The API checks what it can see:

The other conditions — the claim in court or by notarial demand, filing with the AEAT — are yours to meet.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/corrective" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "PARTIAL",
    "rectification_code": "R3",
    "reason": "Bad debt under Art. 80 Cuatro LIVA: more than six months since the tax accrued without collection, claimed by notarial demand.",
    "circumstance_date": "2026-05-04",
    "lines": [
      {
        "description": "Bad debt adjustment - unpaid amount",
        "quantity": -40,
        "unit": "hours",
        "unit_price": 37.5,
        "discount_percentage": 0,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        }
      }
    ],
    "notes": "Notarial demand of 04/05/2026 (Protocol 456/2026). Operation of 15/10/2025."
  }'

Scenario 4 — Correcting the recipient's data (R4)

The invoice recorded its recipient with a wrong name, tax ID or address. Fix the customer first, then send a PARTIAL corrective with rectification_code: R4, no lines and the corrected recipient — for a registered customer, the same customer_id:

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/corrective" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "PARTIAL",
    "rectification_code": "R4",
    "reason": "The customer'\''s tax ID was mistyped on the invoice",
    "recipient": { "customer_id": "{customer_id}" }
  }'

The corrective carries the corrected recipient and leaves the amounts unchanged: its lines negate what is still invoiced and repeat it, so every rate nets to zero and it is issued as PAID. The original becomes RECTIFIED.

Scenario 5 — R5: correcting a simplified invoice

A simplified (F2) invoice is always rectified with R5, whatever the cause. A customer returned one of the two items on the ticket:

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices/{f2_invoice_id}/corrective" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rectification_type": "PARTIAL",
    "rectification_code": "R5",
    "reason": "The customer returned one of the two items on the ticket",
    "lines": [
      {
        "description": "Return - T-shirt size M",
        "quantity": -1,
        "unit_price": 16.53,
        "main_tax": { "type": "IVA", "percentage": 21, "regime_key": "01" }
      }
    ]
  }'

Validation rules BeeL. applies

Which series numbers the corrective

Omit series_id and the corrective is numbered in your company's default series for corrective invoices, never in the original's series: corrective invoices go in a series of their own. If the company has none, it is created on first use (code R, or the next free one). An explicit series_id must be a corrective series. See Series and numbering.

Finding the correctives of an invoice

List invoices filtered by the original: GET /v1/companies/{company_id}/invoices?rectified_invoice_id={invoice_id} returns every corrective issued against it, TOTAL or PARTIAL.

Related