NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Customers

List the customers (deprecated)

Scopecustomers:read

Returns a paginated list of customers, with optional filters.

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

GET
/v1/customers

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

Query Parameters

page?integer

Page number, starting at 1. The response echoes it back as pagination.current_page.

Default1
Range1 <= value
limit?integer

How many items to return per page. The response echoes it back as pagination.items_per_page.

Default20
Range1 <= value <= 100
active?boolean

Filter by active/inactive status. Defaults to true, so inactive customers must be requested explicitly with active=false. Deleted customers are never returned by either value.

search?string

Global search by name, NIF or email

legal_name?string

Filter by legal name (partial search case-insensitive)

nif?string

Filter by NIF (partial search)

email?string

Filter by email (partial search)

phone?string

Filter by phone (partial search)

city?string

Filter by city

province?string

Filter by province

sort_by?string
Value in"legal_name" | "nif" | "email" | "phone" | "city" | "province" | "active" | "created_at"
sort_order?string
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/customers"

Customer list with pagination

{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "legal_name": "Tech Solutions SL",
        "nif": "B12345674",
        "email": "admin@techsolutions.com",
        "phone": "+34912345678",
        "address": {
          "street": "Calle Mayor",
          "number": "15",
          "postal_code": "28013",
          "city": "Madrid",
          "province": "Madrid",
          "country": "España"
        },
        "active": true,
        "created_at": "2024-06-15T10:30:00Z",
        "updated_at": "2025-01-10T14:00:00Z"
      },
      {
        "id": "789abc12-34de-56f7-8901-234567890abc",
        "legal_name": "María García López",
        "nif": "12345678Z",
        "email": "maria.garcia@email.com",
        "phone": "+34654321987",
        "address": {
          "street": "Avenida de la Constitución",
          "number": "25",
          "floor": "3º",
          "door": "B",
          "postal_code": "41001",
          "city": "Sevilla",
          "province": "Sevilla",
          "country": "España"
        },
        "active": true,
        "created_at": "2024-08-20T09:00:00Z",
        "updated_at": "2024-12-01T11:30:00Z"
      },
      {
        "id": "456def78-90ab-12cd-3456-78ef01234567",
        "legal_name": "Distribuidora Levante SA",
        "nif": "A22222222",
        "email": "contabilidad@distribuidoralevante.es",
        "phone": "+34963456789",
        "address": {
          "street": "Polígono Industrial Norte",
          "number": "7",
          "postal_code": "46007",
          "city": "Valencia",
          "province": "Valencia",
          "country": "España"
        },
        "active": false,
        "created_at": "2024-03-10T16:45:00Z",
        "updated_at": "2024-11-20T08:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "items_per_page": 20,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  },
  "meta": {
    "timestamp": "2025-01-20T12:00:00Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "VALIDATION_ERROR",
    "message": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "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"
  }
}

Get a customer (deprecated) GET

Retrieves the complete details of a customer. - **Deprecated:** use `GET /v1/companies/{company_id}/customers/{customer_id}`, which behaves identically. **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.

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.