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

Replace a product (deprecated)

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.

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

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, 10, 21, and the temporary 2, 5 and 7.5 (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 the IVA rates without 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 % (the temporary rate applied from 2022 to electricity, gas and certain foodstuffs) is no longer in force for new operations. AEAT only accepts it on operations dated from 2022-07-01 to 2024-09-30: send the operation_date of that period, because without one the issue date decides and a line at 5 % is rejected with 422 VAT_RATE_NOT_ACCEPTED_ON_DATE. Its equivalence surcharge pair is 0.5 up to 2022-12-31 and 0.62 from 2023-01-01. IVA 2 % and 7.5 % (temporary rates of the last quarter of 2024) are accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26 and 1.

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).

The rate must be one of IrpfPercentage (INVALID_IRPF otherwise) and one the company can bear, the same check as an invoice line (see WithholdingOptions in the tax configuration): an entity gets the rates of individuals rejected with IRPF_RATE_NOT_FOR_CORPORATE_ISSUER, and an individual gets 9.5 rejected with IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER.

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": "INVOICE_NOT_FOUND",
    "message": "Invoice 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": "The invoice must have at least one line",
  "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 (deprecated) 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. **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.

Update a product partially (deprecated) 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. **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.