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

Replace a product

Scopeproducts:write

Replaces an existing product with the body you send.

  • Not a partial update: leaving out main_tax, equivalence_surcharge_rate or irpf_rate resets them to the creation defaults (IVA 21%, 0% and 0%), so send the product complete. To change only some fields, use PATCH /v1/companies/{company_id}/products/{product_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}/products/{product_id}, which is not a drop-in replacement for this one: it changes only the fields present in the body and resets nothing on its own. To reproduce a total replacement, send every field and pass null in the ones you want cleared.
PUT
/v1/products/{product_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

product_idstring

Product unique UUID

Formatuuid

Request Body

code?string|null

Unique alphanumeric product code (optional)

Match^[a-zA-Z0-9_-]*$
Lengthlength <= 50
name?string

Product/service name

Lengthlength <= 255
description?string

Detailed description (optional)

category?string

Product/service category:

  • PRODUCT - Physical, tangible products
  • SERVICE - General services
  • CONSULTING - Consulting and advisory services
  • SOFTWARE - Development, licenses, SaaS
  • TRAINING - Courses, workshops, training
  • OTHER - Other unclassified types
Value in"PRODUCT" | "SERVICE" | "CONSULTING" | "SOFTWARE" | "TRAINING" | "OTHER"
default_price?number

Suggested default price (optional)

Multiple Of0.0001
Range0 <= value
unit?string

Unit of measure (optional)

Lengthlength <= 50
main_tax?

Complete tax information with cross-validations:

  • IVA: real rates 4, 5, 10, 21 (see below for 0)
  • IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real "Tipo Cero"
  • IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)
  • OTHER: any percentage between 0 and 100

0 % under IVA and IPSI is not a rate, it is the exemption sentinel. It is accepted on a line, but only together with an exemption_reason (exempt or non-subject operation); on its own it says nothing and the line is rejected. That is why GET /v1/tax-types publishes 4, 5, 10 and 21 for IVA and not 0: the legitimate way to a 0 % IVA line is through an exemption reason, which the same response also publishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and needs no reason.

IVA 5 % (RD-ley 11/2022 and its extensions, on electricity, gas and basic foodstuffs) is no longer in force for new operations, but it stays valid: corrective invoices and late-filed invoices for the periods when it applied must be able to carry it. Its equivalence surcharge pair is 0.625.

Exception: when regime_key = "17" (OSS/IOSS) the invoice applies the destination country VAT instead of the Spanish one, so any percentage in the EU range [0, 27] is accepted regardless of the tax type set — including 0 without an exemption reason.

equivalence_surcharge_rate?number

Equivalence surcharge percentage (optional).

Must be coherent with main_tax.regime_key: a surcharge > 0 is only valid under regime 18. When regime_key is omitted it is derived automatically (18 with a surcharge > 0, 01 otherwise). An explicit regime_key that does not admit a surcharge combined with a surcharge > 0 is rejected with a 422 (SURCHARGE_REQUIRES_REGIME), and an explicit regime 18 without a surcharge > 0 is rejected with a 422 (REGIME_REQUIRES_SURCHARGE).

Multiple Of0.01
Range0 <= value <= 100
irpf_rate?number

IRPF withholding percentage (optional)

Multiple Of0.01
Range0 <= value <= 100
active?boolean

Indicates whether the product is active

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/products/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "SERV-001",
    "name": "Technical consulting",
    "description": "Specialized technical consulting services in web development",
    "category": "CONSULTING",
    "default_price": 85.5,
    "unit": "hours",
    "main_tax": {
      "type": "IVA",
      "percentage": 21,
      "regime_key": "01"
    },
    "equivalence_surcharge_rate": 5.2,
    "irpf_rate": 15,
    "active": true,
    "created_at": "2025-01-18T10:30:00Z",
    "updated_at": "2025-01-18T15:45:30Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "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": "NOT_FOUND",
    "message": "Resource 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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Data cannot be processed",
    "details": {
      "field": "Specific error description"
    }
  },
  "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"
  }
}

Search the products GET

Searches the active products by name or code and returns at most 20 of them, for autocomplete. - **Deprecated — withdrawn, not moved:** its replacement is `GET /v1/companies/{company_id}/products?q=`, which searches the name, the code **and** the description, so it returns at least everything this endpoint returned. - **Response shape:** it differs, and that is why this notice exists. Here `data` is a plain array of products, limited to 20 active ones, while there `data` is the paginated envelope of the list (`data.products` + `data.pagination`). Change the way you read the response when you migrate.

Update a product partially PATCH

Updates only the fields present in the body, leaving every other field of the product as it is — in particular `main_tax`, `irpf_rate` and `equivalence_surcharge_rate`, which `PUT` resets. - **Null vs omitted:** a field sent as `null` is cleared, which is different from omitting it (see `PatchProductRequest`). The result goes through the same validation as `PUT`. - **Deprecated:** use `PATCH /v1/companies/{company_id}/products/{product_id}`, which behaves identically.