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

Replace a customer

Scopecustomers:write

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}.
  • 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.
PUT
/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

Request Body

nif?string
alternative_id?|null
legal_name?string

Customer legal name. 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. Omitting it clears the field: this is a full replacement, and the creation default (falling back to legal_name) does not apply here.

Lengthlength <= 120
address?

Address you send when you create or update a company, a customer or an onboarding. The street number is mandatory here: an address without it is rejected with 422.

Addresses you read back are described by their own schema, and do not guarantee the street number: records registered before it was collected have none.

phone?string

Phone number. Allows digits, spaces, dashes, parentheses, and optional leading +

Match^[+]?[0-9\s\-\(\)]+$
Length9 <= length <= 20
email?string|null

Email address (minimum valid email is 5 chars, e.g. a@b.co)

Formatemail
Length5 <= length <= 255
website?string|null

Website URL

Match^(https?://.+|)$
Lengthlength <= 255
billing_emails?|null

Additional emails for invoice delivery (optional)

contact_person?string|null

Contact person name (optional)

Lengthlength <= 200
notes?string|null

Additional notes about the customer (optional)

preferred_payment_method?
general_discount?number|null

General discount percentage (optional)

Range0 <= value <= 100
active?boolean

Whether the customer is active or inactive

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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"
  }
}

List the customers GET

Returns a paginated list of customers, with optional filters. - **Deprecated:** use `GET /v1/companies/{company_id}/customers`, which behaves identically.

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.