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

Update a product partially

Scopeproducts:write

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.

PATCH
/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. Send null to clear it.

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

Product/service name. Cannot be cleared.

Lengthlength <= 255
description?string|null

Detailed description. Send null to clear it.

category?string
Value in"PRODUCT" | "SERVICE" | "CONSULTING" | "SOFTWARE" | "TRAINING" | "OTHER"
default_price?number|null

Suggested default price. Send null to clear it.

Multiple Of0.0001
Range0 <= value
unit?string|null

Unit of measure. Send null to clear it.

Lengthlength <= 50
main_tax?
equivalence_surcharge_rate?number|null

Equivalence surcharge percentage. Send null to state that none applies (equivalent to 0).

The merged result must be coherent with the regime key: if this PATCH does not send main_tax.regime_key, the stored regime is adjusted automatically (18 when the merged surcharge is > 0, 01 when it is not). With an explicit regime_key in this PATCH, an incoherent combination is rejected with a 422 (SURCHARGE_REQUIRES_REGIME / REGIME_REQUIRES_SURCHARGE).

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

IRPF withholding percentage. Send null to state that none applies (equivalent to 0).

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 PATCH "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"
  }
}

Replace a product PUT

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.

Delete a product DELETE

Deletes a product from the catalog. - **Deprecated:** use `DELETE /v1/companies/{company_id}/products/{product_id}`, which behaves identically.