CompanyInvoiceLifecycle
Void an issued invoice
Voids an issued invoice of this company. The document is kept and its number is never reused.
- When to use it: the invoice was issued by mistake — the operation never took place, it was a test, or it is an accidental duplicate. If the operation did take place but the invoice is wrong, issue a corrective invoice instead (POST …/{invoice_id}/corrective). The exception is a withholding that should not have been applied: it is not a cause for a corrective, so void the invoice and issue a new one without it.
- Sent or paid: voiding an invoice that was already emailed to the customer or paid requires issued_in_error: true, confirming it was issued by mistake; without it the request fails with 422 VOID_REQUIRES_ISSUED_IN_ERROR. What counts is the fact, not the current status: an email in the invoice's sending history (moving it back from SENT to ISSUED does not erase it), or a paid_at (it stays after the invoice is RECTIFIED). Corrective invoices follow the same rule.
- Corrected invoices: an invoice with live corrective invoices cannot be voided — it was corrected, so the operation took place; issue another corrective (422 INVOICE_HAS_LIVE_CORRECTIVES). A TOTAL corrective cannot be voided either: the invoice it rectifies would stay voided with nothing to offset it (422 TOTAL_CORRECTIVE_NOT_VOIDABLE).
- reason: required, at least 10 characters — it is fiscal data.
- void_date: deprecated. A date earlier than the invoice's issue date is rejected with 422 VOID_DATE_BEFORE_ISSUE_DATE.
- VeriFactu: when it is enabled for the invoice, a cancellation record is submitted to the AEAT.
- PDF: unchanged. The PDF of the invoice stays the one that was delivered; the void is reported by the invoice's status and the invoice.voided webhook.
- Proformas: voiding an ACTIVE proforma is a plain status change with no fiscal effect — no corrective invoice, nothing submitted to the AEAT. The voided proforma is kept as the record of a rejected or withdrawn offer and stays listed.
post/v1/companies/{company_id}/invoices/{invoice_id}/void
Request
- Base URL: https://app.beel.es/api
- URL: https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/void
- 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.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
| 409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
| 409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
Request body
Example request
{
"reason": "Duplicate of invoice F-2026-0142, issued twice by mistake",
"void_date": "2025-01-20"
}Response
Invoice voided successfully
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.