Restore a discarded payment event
Scopepayment-connections:writeReverses a previous discard, bringing a payment event back into the default list.
The operation reverses the whole discard operation: the event named in the request and
every event with the same payment identity (see the discard operation) that was discarded
together with it, that is, with exactly the same deleted_at timestamp. Events discarded
in an earlier or later operation are not affected. Idempotent — restoring an event that is
not discarded is a no-op.
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 events belong to — 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.
uuidUnique identifier (UUID) of the payment connection the operation acts on, as returned by GET /v1/companies/{company_id}/payment-connections. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers 404, exactly like one that does not exist.
uuidIdentifier of the payment event, as returned by the list operation.
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
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. |
^[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/payment-connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/restore"{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"provider": "stripe",
"event_type": "payment_intent.succeeded",
"event_kind": "PAYMENT_COMPLETED",
"external_event_id": "evt_1234567890",
"external_payment_id": "pi_1234567890",
"source_object_id": "in_1234567890",
"currency": "EUR",
"amount": 150,
"fee_amount": 0,
"net_amount": 0,
"category": "DIRECT_PAYMENT",
"money_returned": true,
"customer_email": "string",
"customer_name": "string",
"status": "RECEIVED",
"invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
"invoice_number": "2026/0042",
"failure_category": "USER_CONFIGURATION",
"failure_reason": "MISSING_DEFAULT_SERIES",
"failure_message": "string",
"needs_action": true,
"outcome": "INVOICED",
"draft_available": true,
"retry_available": true,
"discard_available": true,
"retry_count": 0,
"received_at": "2019-08-24T14:15:22Z",
"processed_at": "2019-08-24T14:15:22Z",
"description": "string",
"payment_method": "CARD",
"discarded": true,
"discarded_at": "2019-08-24T14:15:22Z"
},
"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": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "EVENT_NOT_FOUND",
"message": "Payment event not found"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Data cannot be processed",
"details": {
"field": "Specific error description"
}
},
"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"
}
}Discard a payment event POST
Removes a payment event from the default list (soft delete). The event stays in the audit trail and can be brought back with the restore operation. The operation applies to the whole payment the event belongs to. Its scope is every active, eligible event of the connection that shares the payment identity of the event named in the request: when the event carries a payment identifier (`external_payment_id`), every event with that same identifier, whatever its kind (the sale, its failed attempts, its refunds); otherwise, when it carries a source object (`source_object_id`, such as a credit note or a dispute), every event with that same source object; otherwise, the event alone. All of them are discarded together, in a single transaction and with the same `deleted_at` timestamp. Events that are not eligible remain unchanged, and so do events still in `RECEIVED` state other than the one named in the request: they have not been processed yet and are left for processing. The response carries the event named in the request. - **Eligible events:** an event already linked to an issued invoice, or currently being processed, cannot be discarded; the request returns `400`.
List the tax types allowed in Spain GET
Returns the tax regimes and percentages that BeeL accepts on an invoice. Use it to validate a rate before sending it, or to build your own picker instead of hard-coding the percentages. - **Contents:** VAT (mainland), IGIC (Canary Islands), IPSI (Ceuta and Melilla), the withholding (IRPF) percentages, the equivalence surcharge that corresponds to each VAT rate, and the exemption reasons with the classification each one implies. - **Scope:** the catalogue is the same for every credential and does not depend on any account or on any NIF, so the operation takes no identifier and works before the first NIF exists. ## VAT rates and the zero case - **VAT lists 2, 4, 5, 7.5, 10 and 21, and deliberately not 0:** under VAT (and IPSI) a 0 % is not a rate but the exemption/non-subject sentinel, and on its own it says nothing. A 0 % line is only valid together with an `exemption_reason`, which this same response publishes under `exemption_reasons`. - **IGIC does list 0:** there it is the real "Tipo Cero" and needs no reason. - **Temporary VAT rates carry their period:** 5 % (2022-07-01 to 2024-09-30), and 2 % and 7.5 % (2024-10-01 to 2024-12-31) are listed with `valid_from` / `valid_until`. They no longer apply to new operations but stay listed, because correctives and late filings for those periods still need them; an invoice whose operation date falls outside the period is rejected with `422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Every other rate has both `null`. - **Equivalence surcharges are listed per VAT ↔ surcharge pair**, each with its period.