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

Create a product (deprecated)

Scopeproducts:write

Creates a new product or service in the catalog.

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

POST
/v1/products

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

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

code?string|null

Unique alphanumeric product code (optional)

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

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/products" \  -H "Content-Type: application/json" \  -d '{    "name": "Technical consulting"  }'
{
  "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": "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"
  }
}

Delete several products of a company DELETE

Deletes the products listed in `ids` from the catalog of this company, up to 100 IDs per request; send several requests for more. - **Partial operation:** the response reports which products were deleted (`deleted_products`) and which failed (`errors`, one entry per product with its `product_id`), with the counts in `summary`. That is why it answers `200` with a body instead of `204`.

Get a product (deprecated) GET

Retrieves the details of a product. - **Deprecated:** use `GET /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.