Products

Create a product

Creates a new product or service in the catalog.

  • Deprecated: use POST /v1/companies/{company_id}/products, which behaves identically.

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

post/v1/products

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/products
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

codestring nullable

Unique alphanumeric product code (optional)

namestring required

Product/service name

descriptionstring

Detailed description (optional)

category'PRODUCT' | 'SERVICE' | 'CONSULTING' | 'SOFTWARE' | 'TRAINING' | 'OTHER'

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
default_pricenumber

Suggested default price (optional)

unitstring

Unit of measure (optional)

equivalence_surcharge_ratenumber

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

irpf_ratenumber

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.

Example request

{
  "code": "SERV-001",
  "name": "Technical consulting",
  "description": "Specialized technical consulting services",
  "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
}

Response

Product created successfully

successboolean required

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.