Customer Import

Delete several customers

Deletes the customers listed in ids.

  • Deprecated: use DELETE /v1/companies/{company_id}/customers/bulk, which behaves identically.

Partial results

  • Partial: the customers that can be deleted are deleted, and the rest keep their place in customers_deletion with the status that explains why.
  • HAS_INVOICES: a customer that has invoices cannot be deleted and comes back with that row status.

What deleting means

  • Semantics: each deletion behaves as DELETE /v1/customers/{customer_id}. The customer is retained for tax record-keeping purposes but is no longer exposed by the API, its identifier is released for reuse, and invoices already issued to it keep their own copy of the recipient's details.
  • Not deactivating: deleting frees the identifier, so the same NIF can be registered again, while PATCH with active: false leaves the customer where it is with its NIF still taken.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

delete/v1/customers/bulk

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/customers/bulk
  • Auth: HTTP bearer

Query parameters

idsstring required
Example:550e8400-e29b-41d4-a716-446655440000,550e8400-e29b-41d4-a716-446655440001

Comma-separated customer IDs

Response

Request processed. Always 200 when the batch was processed, even if not a single customer could be deleted: the status code says whether the request was understood and run, not whether every row went well. The per-row split is in the report.

successboolean required

Example response

{
  "success": true,
  "data": {
    "metadata": {
      "total_customers": 10,
      "operation": "DELETE_CUSTOMERS"
    },
    "customers_deletion": [
      {
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "DELETED",
        "error": {
          "code": "CLIENT_HAS_INVOICES",
          "message": "A customer with invoices cannot be deleted: its tax record is kept intact. Deactivate it (active: false) to stop using it."
        }
      }
    ],
    "statistics": {
      "total_processed": 10,
      "deleted": 7,
      "not_found": 1,
      "has_invoices": 2
    },
    "deleted_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "deactivated_ids": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "total": 10,
    "successful": 8,
    "failed": 2,
    "errors": [
      {
        "customer_id": "550e8400-e29b-41d4-a716-446655440000",
        "error": {
          "code": "CLIENT_HAS_INVOICES",
          "message": "A customer with invoices cannot be deleted: its tax record is kept intact. Deactivate it (active: false) to stop using it."
        }
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.