Skip the next generation of a recurring invoice
Scopeinvoices:writeSkips the next scheduled invoice generation and advances the generation date to the following period. Nothing is issued.
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
NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.
uuiduuidHeader 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) - If the same key is sent twice, the result of the first operation is returned
- Keys 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 and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/recurring-invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/skip"{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"frequency": "MONTHLY",
"day_of_month": 0,
"start_date": "2019-08-24",
"end_date": "2019-08-24",
"next_generation": "2019-08-24",
"preview_days": 3,
"status": "ACTIVE",
"pause": {
"reason": "USER",
"since": "2019-08-24T14:15:22Z",
"blocker": "NIF_NOT_REGISTERED"
},
"series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c",
"series_code": "string",
"invoice_type": "STANDARD",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"recipient_fiscal_name": "string",
"recipient_nif": "string",
"lines": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"order": 0,
"description": "string",
"quantity": 0,
"unit": "string",
"unit_price": 0,
"discount_percentage": 0,
"tax_type": "string",
"vat_rate": 0,
"regime_key": "string",
"equivalence_surcharge_rate": 0,
"irpf_rate": 0,
"exemption_reason": "EXENTA_ART_20",
"exemption_reason_text": "string"
}
],
"payment_method": "string",
"notes": "string",
"verifactu_enabled": true,
"send_automatically": true,
"email_configuration": {
"recipients": [
"string"
],
"cc": [
"string"
],
"subject": "string",
"message": "string"
},
"generated_invoices": 0,
"last_generated_at": "2019-08-24T14:15:22Z",
"source_invoice_id": "0c7d5f47-8759-4ef4-82d5-705413539f77",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation error",
"details": {
"field_name": "Field is required"
}
},
"meta": {
"timestamp": "2025-01-15T10: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": "La factura debe tener al menos una línea",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Resource not found"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"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"
}
}Set the status of a recurring invoice PUT
Sets the lifecycle status of a recurring invoice template. This is how generation is paused and resumed. - **`PAUSED`:** stops automatic generation, keeping the schedule configuration intact. - **`ACTIVE`:** resumes generation and recalculates the next generation date from today. - **`COMPLETED`:** reached on its own when the schedule runs out. It cannot be set here; the body only accepts `ACTIVE` and `PAUSED`. - **Rejected transitions:** resuming a template that is already active, or one whose `pause.blocker` is still in effect.
Generate an invoice now from a recurring template POST
Runs the generation of this recurring template immediately, out of its schedule. It is a fiscal act: the generated invoice consumes numbering from the series of the template and, when the template says so, is issued and sent. - **It brings the upcoming occurrence forward, it does not add one:** the call consumes the period that was pending, so the invoice is created now and `next_generation` advances one period. Generating manually, skipping and letting the schedule run each consume exactly one occurrence, so a monthly template still produces twelve invoices a year however you mix the three. - **`next_generation` in the response:** the template's next date after this call consumed the pending occurrence, or `null` when the advance took the template past its `end_date` and its status is now `COMPLETED`. - **An extra invoice outside the calendar:** do not use this endpoint. Create a normal invoice, or derive a draft from one the template already generated with `POST /v1/companies/{company_id}/invoices/derivations`. Either way the schedule stays where it was.