NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Customers

Delete a customer

Scopecustomers:write

Deletes a customer that has no invoices.

What deleting means

  • No longer exposed: the customer is retained internally for tax record-keeping purposes, but is no longer exposed by the API: subsequent requests to it return 404, and it is never included in the customer list, under any value of the active filter.
  • Identifier released: its NIF or alternative identifier is freed, so a new customer may be created with the same identifier.

Customers you cannot delete

  • Customers with invoices: they cannot be deleted and the request answers 409 CLIENT_HAS_INVOICES, leaving the customer untouched — neither deleted nor deactivated.
  • Deactivating instead: to stop using a customer, whether or not it has invoices, update it with active set to false: that releases no identifier and keeps the customer retrievable through GET /v1/customers?active=false.
DELETE
/v1/customers/{customer_id}

Authorization

AuthorizationBearer <token>

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

customer_idstring

Customer ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://app.beel.es/api/v1/customers/550e8400-e29b-41d4-a716-446655440000"
{
  "success": true,
  "data": {
    "message": "Customer deleted successfully"
  },
  "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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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": "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"
  }
}

Update a customer partially PATCH

Updates only the fields present in the body, leaving every other field of the customer as it is. - **Null vs omitted:** a field sent as `null` is cleared, which is different from omitting it (see `PatchCustomerRequest`). The result goes through the same validation as `PUT`. - **Deprecated:** use `PATCH /v1/companies/{company_id}/customers/{customer_id}`, which behaves identically.

Download the customer import template POST

Downloads a sample CSV for customer import: the required headers plus example rows, written with a UTF-8 byte order mark so that Excel opens it with the accents intact. - **Deprecated:** use `GET /v1/templates/customer-import`, which returns the same file. Reading a fixed template is not a `POST`, and the template belongs to no customer. - **Retirement:** the response announces the retirement date in its `Sunset` header.