# Replace a customer (deprecated) API Reference 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. ## PUT /v1/customers/{customer_id} **Replace a customer** 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. **Deprecated.** ### Authentication Accepts any of: - `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`) ### Parameters - **customer_id** (required) in path: Customer ID ### Request Body Required. **Content `application/json`:** - **nif**: New Spanish Tax ID for the customer. Mutually exclusive with `alternative_id`. Omit to keep the current identifier. - **alternative_id**: New alternative identifier (non-Spanish customers). Mutually exclusive with `nif`. Omit to keep the current identifier. - **legal_name** `string`: Customer legal name. Matched against the AEAT census only for individuals; for a company the name is **not verified**. - **trade_name** `string`: Customer trade name. Omitting it **clears** the field: this is a full replacement, and the creation default (falling back to `legal_name`) does not apply here. - **address** `Address`: Address you send when you create or update a company, a customer or an onboarding. A required field made only of whitespace passes the length checks below but leaves the address without that part, so it is rejected with `422`: `STREET_EMPTY`, `POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`. Addresses you read back are described by their own schema. - **phone** `PhoneInput`: A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces, dashes, parentheses and an optional leading `+`. Every request that takes a phone number uses this schema. It is `Phone` plus the rules enforced on input. A value this schema accepts always satisfies `Phone`, so anything you send here is something a response can return. - **email** `string` (email): Main contact address (minimum valid email is 5 chars, e.g. a@b.co). Invoice emails go here only when the customer has no `billing_emails`. - **website** `string`: Website URL - **billing_emails** `array[Email]`: 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. - **contact_person** `string`: Contact person name (optional) - **notes** `string`: Additional notes about the customer (optional) - **preferred_payment_method** `PaymentInfo` - **general_discount** `number`: General discount percentage (optional) - **active** `boolean`: Whether the customer is active or inactive ### Responses #### 200: Customer updated successfully **Content `application/json`:** - **success** (required) `boolean`: No description (example: true) - **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - **meta** `ResponseMeta` - **data** `Customer` #### 400: `INVALID_JSON_FORMAT` — the body is not valid JSON, or a property has the wrong type or format (a string where a number is expected, a date that does not parse, a malformed UUID, a boolean that is not `true`/`false`). The `details` object follows `FieldDeserializationError`: `field`, `invalid_value` and, where there is one, `expected_format` (or `allowed_values`, for a boolean). A property the operation does not declare is not a format error: it is ignored. A value outside an **enum**'s vocabulary is not answered here. The property is a well-formed string that names nothing the operation knows, so it is judged as content: `422` (`VALIDATION_ERROR`), with the same `FieldDeserializationError` shape in `details` (`field`, `invalid_value`, `allowed_values`). **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") - **error**: No description **Example:** ```json { "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" } } ``` #### 401: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 403: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by `error.code`; an operation that adds a cause of its own names it in its `403`. You can branch on them exhaustively. - `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires; `error.details.missing_scopes` names them as a single comma-separated string (for example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the same shape and lists every scope the operation needs. Retrying will not help: mint a key that holds them. - `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only lets you read it. - `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account, or the management relationship you hold over it, does not cover this operation. - `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer when it does not exist, so existence is never disclosed. - `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the one named by `BeeL-Active-Company`, is not one this credential may reach — and again, this is also the answer when it does not exist. - `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was already in flight, so the write was rejected and nothing was recorded. Retrying will not help until the access is granted again. - `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came from a test API key (`beel_sk_test_…`). Use your live key or the dashboard. - `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the operation needs; `error.details.feature_code` names it. This gate runs **before** the scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first. - `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be evaluated against one. Fail-closed, not a permission that can be granted to you. - `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no API key and no OAuth2 token can perform it, whatever scopes it holds. - `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API key can hold (such as `accounts:write`), so a dashboard session never satisfies it. - `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and the account has no Live mode yet. It is never degraded to Test: use your test key, or activate Live first. - `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account in the path, but it is not the account in focus. Switch focus to it and retry. - `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its body, usually because a text field carries something that looks like markup or a script (HTML tags, `