Customers

Update a customer partially (deprecated)

Scopecustomers:write

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.
AEAT census: the customer's Spanish tax identifier is only checked against the AEAT census when the request changes the nif or the legal_name. Editing anything else never asks the census. For a legal entity the census checks the CIF only and its legal_name is not verified, so the name never causes the rejection; only a natural person's NIF is crossed with the name. Duplicate and format checks run on every update.
Deprecated: use PATCH /v1/companies/{company_id}/customers/{customer_id}, which behaves identically.

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

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

Request Body

nif?string

alternative_id?|null

legal_name?string

Customer legal name. Cannot be cleared. Matched against the AEAT census only for individuals; for a company the name is not verified.

Length1 <= length <= 120

trade_name?string|null

Customer trade name. Send null to clear it.

Lengthlength <= 120

address?

phone?string

email?string|null

Main contact address. Invoice emails go here only when the customer has no billing_emails. Send null to clear it.

Formatemail

Length5 <= length <= 255

website?string|null

Website URL. Send null to clear it.

Match^(https?://.+|)$

Lengthlength <= 255

billing_emails?|null

Addresses that receive the customer's invoice emails. When the send request names no recipients and the invoice has no email_config recipients, invoices go to these addresses, and not to email; email is used only when billing_emails is empty. Replaced as a whole; send null or [] to remove them all.

contact_person?string|null

Contact person name. Send null to clear it.

Lengthlength <= 200

notes?string|null

Additional notes. Send null to clear it.

preferred_payment_method?

general_discount?number|null

General discount percentage. Send null to clear it.

Range0 <= value <= 100

active?boolean

Whether the customer is active or inactive.

Response Body

application/json

curl -X PATCH "https://app.beel.es/api/v1/customers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X PATCH "https://app.beel.es/api/v1/customers/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "legal_name": "Empresa Cliente SL",
    "trade_name": "EmpresaCliente",
    "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": "string",
    "billing_emails": [
      "user@example.com"
    ],
    "contact_person": "María García",
    "notes": "string",
    "preferred_payment_method": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "general_discount": 0,
    "active": true,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "alternative_id": {
      "type": "NIF_IVA",
      "number": "string",
      "country_code": "st"
    }
  },
  "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": "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": "INVOICE_NOT_FOUND",
    "message": "Invoice 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": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {
      "legal_name": "The field 'legal_name' cannot be empty",
      "recipient.address.postal_code": "Contains invalid characters."
    }
  },
  "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"
  }
}

Replace a customer (deprecated) PUT

Replaces an existing customer with the body you send. - **Not a partial update:** `trade_name`, `email`, `website`, `billing_emails`, `contact_person`, `notes` and `general_discount` are cleared when they are absent from the body, so send the customer complete. To change only some fields, use `PATCH /v1/companies/{company_id}/customers/{customer_id}`. - **AEAT census:** the customer's Spanish tax identifier is only checked against the AEAT census when the body changes the `nif` or the `legal_name` of the stored customer. Resending the same pair never asks the census, so a customer stored long ago stays editable even if its NIF is no longer listed. For a **legal entity** the census checks the CIF only and its `legal_name` is not verified, so the name never causes the rejection; only a **natural person**'s NIF is crossed with the name. Duplicate and format checks run on every update. - **Deprecated:** this route will be retired on the date announced in its `Sunset` response header. The canonical form has a single update verb, `PATCH /v1/companies/{company_id}/customers/{customer_id}`, which is not a drop-in replacement for this one: it changes only the fields present in the body. To reproduce a total replacement, send every field and pass `null` in the ones you want cleared. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Delete a customer (deprecated) DELETE

Deletes a customer that has no invoices. - **Deprecated:** use `DELETE /v1/companies/{company_id}/customers/{customer_id}`, which deletes the same way but answers `204` with no body instead of `200`. This route keeps working until the date announced in its `Sunset` response header. ## 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. - **Customers used by a recurring invoice:** while an active or paused recurring invoice has the customer as its recipient, the request answers `400` `REFERENCED_BY_RECURRING_INVOICE`. - **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`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Update a customer partially (deprecated)

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json