Update an invoice
Scopeinvoices:writeUpdates only the fields present in the body, leaving every other field of the invoice as it is.
- Status: only an invoice in
DRAFTorSCHEDULED, or a proforma inACTIVE, can be modified; any other status answers422withSTATUS_NOT_MODIFIABLE. An issued one is amended with a corrective invoice (POST …/{invoice_id}/corrective) or voided. - Series: changing
series_idnever moves the invoice to another NIF — a series of another company is not visible from here.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidInvoice ID
uuidHeader Parameters
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 other than 503, check whether the operation took effect before retrying with a new key - After a
503, retry first with the same key. If the response carriesIdempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once - A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
POSToperations that only read data (exports, batch PDF downloads, previews) ignore this header: they run on every call and their response is never stored
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 a few times. If it keeps answering 409, the first response could not be stored: check the resource instead of retrying. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"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.
dateNew 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.
dateOffer 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.
dateReplaces the custom fields of the invoice as a whole: the list sent becomes the new
list. Omit it to keep the current ones; send null or [] to remove them all. The
same rules as on creation apply: at most one value per key, a key the company does
not have answers 422 CUSTOM_FIELD_UNKNOWN and an archived field answers
409 CUSTOM_FIELD_ARCHIVED, even when the draft already carries it. Every field in
the list is saved again with the label it has now. Only a draft, a scheduled invoice
or an active proforma can change them; any other status answers
422 STATUS_NOT_MODIFIABLE.
When the request changes the recipient and omits custom_fields, the saved fields are
carried over to the new customer; one archived since is left out, with no error.
They are informational: they are not part of the VeriFactu record sent to the AEAT and do not enter its hash.
items <= 20Processing options for the draft. Fields are optional and follow partial update semantics: omitted fields preserve the existing value.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000" \ -H "Content-Type: application/json" \ -d '{ "lines": [ { "description": "Corporate website development - Updated", "quantity": 45, "unit": "hours", "unit_price": 40, "discount_percentage": 5, "main_tax": { "type": "IVA", "percentage": 21, "regime_key": "01" } }, { "description": "Web maintenance - 3 months", "quantity": 3, "unit": "month", "unit_price": 150, "discount_percentage": 0, "main_tax": { "type": "IVA", "percentage": 21, "regime_key": "01" } } ], "payment_info": { "method": "DIRECT_DEBIT", "iban": "ES9121000418450200051332" }, "notes": "Invoice updated with new maintenance line. Payment via direct debit." }'{
"success": true,
"data": {
"invoice_number": "2025/0001",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "FAC"
},
"number": 1,
"type": "STANDARD",
"status": "SCHEDULED",
"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",
"scheduled_action": "DRAFT",
"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",
"logo_url": "string",
"additional_info": "Nº Colegiado: 12345"
},
"recipient": {
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"legal_name": "Empresa SL",
"trade_name": "Empresa",
"nif": "12345678A",
"alternative_id": {
"type": "NIF_IVA",
"number": "string",
"country_code": "st"
},
"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",
"exemption_reason_text": "string",
"taxable_base": 1800,
"line_total": 2178,
"pricing_mode": "UNIT_PRICE",
"total_excluding_tax": 1,
"total_including_tax": 100,
"line_type": "NORMAL",
"nature": "SERVICES",
"source_invoice_reference": "string",
"source_invoice_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"totals": {
"taxable_base": 2000,
"total_discounts": 0,
"vat_breakdown": [
{
"type": 21,
"base": 2000,
"amount": 420,
"regime_key": "18"
}
],
"total_vat": 420,
"surcharge_breakdown": [
{
"type": 0,
"base": 0,
"amount": 0
}
],
"total_equivalence_surcharge": 0,
"irpf_breakdown": [
{
"type": 0,
"base": 0,
"amount": 0
}
],
"total_irpf": 300,
"invoice_total": 2120,
"total_disbursements": 0,
"total_to_pay": 2120
},
"payment_info": {
"method": "BANK_TRANSFER",
"iban": "ES1234567890123456789012",
"swift": "ABCDESMMXXX",
"payment_term_days": 30
},
"notes": "string",
"replaced_invoice_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"void_cause": "VOID_REQUEST",
"void_reason": "string",
"voided_at": "2025-01-20T09:12:44Z",
"rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
"source_proforma_id": "5f6c4143-c67e-4332-9fbc-f68d1420128f",
"converted_invoice_id": "c85716fe-5512-4945-9dc8-daa0106a270b",
"replaced_by_invoice_id": "702b9a3f-6b76-4b62-982a-d1b3ea3c85a9",
"rectified_by_invoice_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"rectification_reason": "string",
"recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
"recurring_invoice_name": "string",
"rectification_type": "TOTAL",
"rectification_code": "R1",
"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"
},
"send_automatically": true,
"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": {
"enabled": true,
"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...",
"registered_at": "2019-08-24T14:15:22Z",
"submission_status": "ACCEPTED",
"skip_reason": "CONFIG_DISABLED",
"error_code": "3000",
"error_message": "Factura ya existe en el sistema"
},
"attachments": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"url": "string",
"type": "string"
}
],
"sending_history": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"recipients": [
"string"
],
"cc": [
"string"
],
"subject": "string",
"status": "QUEUED",
"sent_at": "2025-01-29T18:45:00Z",
"external_message_id": "string",
"error": "string"
}
],
"email_delivery": {
"status": "REJECTED",
"reason": "error.email.envio_no_permitido"
},
"deleted_at": "2019-08-24T14:15:22Z",
"id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"rendering": {
"invoice_design_id": "d08ccbee-29d3-4d14-8af3-8c9e959d1ee0",
"invoice_design_version": 3,
"language": "es"
},
"custom_fields": [
{
"key": "store",
"label": "Store",
"value": "Gran Vía 12"
}
],
"compliance": [
{
"type": "VERIFACTU",
"status": "FULFILLED",
"system_status": "verifactu:ACCEPTED",
"stamps": [
{
"key": "verifactu-qr",
"value": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1590.00"
},
{
"key": "verifactu-hash",
"value": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B"
}
],
"updated_at": "2025-01-20T10:15:03Z"
}
]
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INVALID_JSON_FORMAT",
"message": "The field 'due_date' has an invalid date format: '2026-03-04fds'. Expected format: YYYY-MM-DD.",
"details": {
"field": "due_date",
"invalid_value": "2026-03-04fds",
"expected_format": "YYYY-MM-DD"
}
},
"meta": {
"timestamp": "2026-03-05T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "Invoice not found"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "CUSTOM_FIELD_ARCHIVED",
"message": "The custom field store is archived and cannot be added to an invoice."
},
"meta": {
"timestamp": "2026-10-17T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}The body parses but one or more values are not acceptable. details is a flat map from the offending property (snake_case, nested paths joined with a dot) to a message; one entry per property.
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid.",
"details": {
"nif": "The field 'nif' cannot be empty",
"lines": "The field 'lines' cannot be empty",
"recipient.address.postal_code": "Contains invalid characters."
}
},
"meta": {
"timestamp": "2025-01-20T10:00:00Z",
"request_id": "c3c3c3c3-0003-4000-a000-000000000003"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Create an invoice POST
Creates an invoice for this company. The issuer data comes from the company in the path, and the document is created as a draft unless you ask for it to be issued. - **Issuing:** `options.issue_directly` numbers and issues the invoice in the same call. Submission to the AEAT is asynchronous, so `verifactu.submission_status` comes back as `PENDING`: a 2xx means the invoice was accepted for submission, not that the AEAT has registered it. If the number the series would assign is already used by another invoice of the same company, in this series or in another one, it fails with `400 SERIES_NUMBER_COLLISION` without issuing anything or consuming a number: the series needs review, so contact support. - **Document type:** `type` chooses the document. A `PROFORMA` is non-fiscal — it is born `ACTIVE`, numbered `PRO-...` from its own non-fiscal series, and ignores `issue_directly`. - **Related:** to copy an existing invoice into a new draft, use `POST …/invoices/derivations`, which carries neither `type`, nor `recipient`, nor `lines`.
Derive a draft invoice from an existing one POST
Creates a draft invoice derived from an existing invoice of this company. The source invoice, named in `from_invoice_id`, is not modified. - **`mode`:** the only value is `DUPLICATE`, which copies the source into a fresh draft. Recipient, lines, payment method, series and observations are copied; number, status, dates, VeriFactu data and PDF are reset. - **Custom fields:** copied from the source, each with the label the field has now. A field the company has archived since is left out instead of failing the call. - **Series:** the one sent in `series_id`, or the source's when omitted. It is validated against the type of the copy, which is not always the source's: the copy of a `CORRECTIVE` is born `STANDARD`. An incompatible series fails with `422 SERIES_INCOMPATIBLE_DOC_TYPE`.