Invoices

Update an invoice

Updates an invoice in DRAFT or SCHEDULED status, or a proforma in ACTIVE.

  • Deprecated: use PATCH /v1/companies/{company_id}/invoices/{invoice_id}, the single update verb of the canonical form.
  • Difference: only the verb changes. Both update just the fields present in the body and leave every other one untouched.

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

put/v1/invoices/{invoice_id}

Request

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

Path parameters

invoice_idstring uuid required

Universally Unique Identifier (UUID v4)

Example:550e8400-e29b-41d4-a716-446655440000

Invoice ID

Headers

BeeL-Active-Companystring uuid

Which company (tax ID) the request operates on.

An API key belongs to an account, and an account may hold several companies. Endpoints that read or write company-owned data — invoices, customers, products, series, tax and VeriFactu settings — resolve their target company from this header when the path does not already name one.

On a path that names the company, such as /v1/companies/{company_id}/invoices, the path is the target and this header is not read at all: it neither switches the target nor makes the request fail, so sending one that disagrees with the path is silently ignored rather than rejected. Prefer those paths whenever you need to be explicit about which tax ID you are operating on.

On an account holding a single company the header may be omitted — that company is used. On an account holding several it is required: the request fails with 403 ACTIVE_COMPANY_REQUIRED otherwise. A company-owned record always belongs to one tax ID, so operating on it without saying which one has no meaning.

The company does not have to belong to the API key's own account: one you manage works too, which is what makes the company_id returned by POST /v1/accounts usable here to invoice on a provisioned account's behalf. What you may do with it is then decided by your access level over that account, and issuing also requires a signed fiscal representation.

This header is how you operate on a company, never how you find one: a value you do not reach answers 403, the same as one that does not exist, so guessing reveals nothing. Get the company_id from the response that created the company.

Requires the companies:read scope. Returns 403 if the company is neither yours nor one you manage.

Request body

type'STANDARD' | 'CORRECTIVE' | 'SIMPLIFIED' | 'PROFORMA'
  • STANDARD: Standard invoice
  • CORRECTIVE: Corrects or cancels a previous invoice
  • SIMPLIFIED: Simplified invoice (ticket), for a recipient that is not identified. BeeL. requires a STANDARD invoice when the recipient is identified, at any amount: a SIMPLIFIED invoice whose recipient carries an nif or alternative_id is rejected with SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT. The only amount BeeL enforces is a cap of 3,000€ VAT included (SIMPLIFIED_INVOICE_EXCEEDS_LEGAL_LIMIT). The general limit of RD 1619/2012 is 400€ (art. 4.1.a); up to 3,000€ applies only to the activities listed in art. 4.2. BeeL does not check which activity the issuer carries out.
  • PROFORMA: Commercial document (formal quote) with no fiscal validity. Never enters VeriFactu (no QR, no AEAT submission): verifactu.enabled is always false, whatever the company's regime. Requires full recipient data, like STANDARD. Cannot be corrective nor reference a rectified invoice.
series_idstring uuid

Universally Unique Identifier (UUID v4)

operation_datestring date nullable

Date when the operation occurred. Must be today or a past date, and not more than twenty years before today (AEAT does not accept an older one): an older date answers 422 OPERATION_DATE_TOO_OLD, on update and again on issue. Set to null to clear (operation date = issue date). If not provided, keeps the existing value.

due_datestring date nullable

New due date. Must be the same as or after issue_date. Set to null to clear the due date. If not provided, keeps the existing value.

valid_untilstring date nullable

Offer validity date. Only rendered on PROFORMA invoices; on any other invoice type the field is inert. Purely informational. Set to null to clear it. If not provided, keeps the existing value.

notesstring

Example request

{
  "series_id": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "customer_id": "4f244735-980b-8d9c-80e8-6331fa0b1958"
  },
  "lines": [
    {
      "total_excluding_tax": 1,
      "total_including_tax": 100,
      "main_tax": {
        "type": "IVA",
        "percentage": 21,
        "regime_key": "01"
      },
      "equivalence_surcharge_rate": 5.2,
      "irpf_rate": 15,
      "exemption_reason": "EXENTA_ART_20",
      "line_type": "NORMAL"
    }
  ],
  "payment_info": {
    "method": "BANK_TRANSFER",
    "iban": "ES1234567890123456789012",
    "swift": "ABCDESMMXXX",
    "payment_term_days": 30
  },
  "custom_fields": [
    {
      "key": "store",
      "value": "Gran Vía 12"
    }
  ],
  "options": {
    "email_config": {
      "recipients": [
        "client@example.com"
      ],
      "cc": [
        "accounting@example.com"
      ],
      "subject": "Invoice 2025/0001 - Development services",
      "message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
    }
  }
}

Response

Invoice updated successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "invoice_number": "2025/0001",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "FAC"
    },
    "number": 1,
    "issue_date": "2025-01-15",
    "operation_date": "2025-01-10",
    "due_date": "2025-02-14",
    "valid_until": "2025-02-28",
    "payment_date": "2025-01-20",
    "sent_at": "2025-01-29T18:45:00Z",
    "paid_at": "2025-02-05T10:30:00Z",
    "auto_emit_after": "2025-03-20",
    "scheduled_for": "2025-02-15",
    "issuer": {
      "legal_name": "Juan Pérez García",
      "trade_name": "JP Web Development",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      },
      "phone": "+34 612 345 678",
      "email": "user@example.com",
      "website": "https://beel.es",
      "additional_info": "Nº Colegiado: 12345"
    },
    "recipient": {
      "legal_name": "Empresa SL",
      "trade_name": "Empresa",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      },
      "phone": "+34 612 345 678",
      "email": "user@example.com"
    },
    "lines": [
      {
        "description": "Web application development",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 50,
        "discount_percentage": 10,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "equivalence_surcharge_rate": 5.2,
        "irpf_rate": 15,
        "exemption_reason": "EXENTA_ART_20",
        "taxable_base": 1800,
        "line_total": 2178,
        "total_excluding_tax": 1,
        "total_including_tax": 100,
        "line_type": "NORMAL"
      }
    ],
    "totals": {
      "taxable_base": 2000,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 2000,
          "amount": 420,
          "regime_key": "18"
        }
      ],
      "total_vat": 420,
      "total_irpf": 300,
      "invoice_total": 2120,
      "total_to_pay": 2120
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "voided_at": "2025-01-20T09:12:44Z",
    "external_ref": "ORD-2025-0042",
    "metadata": {
      "external_customer_id": "cus_ULGk8bzIr88aag",
      "external_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "payment_intent_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
      "charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
      "payment_provider": "STRIPE_CONNECT",
      "external_order_id": "ORD-2025-0042"
    },
    "email_config": {
      "recipients": [
        "client@example.com"
      ],
      "cc": [
        "accounting@example.com"
      ],
      "subject": "Invoice 2025/0001 - Development services",
      "message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
    },
    "pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440000/pdf",
    "verifactu": {
      "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
      "registration_number": "4f8c2a1e-9b3d-4e7a-8c5f-1d2e3f4a5b6c",
      "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1590.00",
      "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
      "submission_status": "ACCEPTED",
      "skip_reason": "CONFIG_DISABLED",
      "error_code": "3000",
      "error_message": "Factura ya existe en el sistema"
    },
    "sending_history": [
      {
        "sent_at": "2025-01-29T18:45:00Z"
      }
    ],
    "email_delivery": {
      "status": "REJECTED",
      "reason": "error.email.envio_no_permitido"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "custom_fields": [
      {
        "key": "store",
        "label": "Store",
        "value": "Gran Vía 12"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

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