Products
Create several products
Creates up to 100 products in one call.
- Partial operation: each product is processed and reported independently, so a row the domain rejects — a rate BeeL does not accept, a duplicate code — comes back inside the report while the rest are created.
- Status code: always 201 when the batch was processed, even if not a single product could be created. A malformed request — a missing field, an empty array, more than 100 items — answers 422 instead and nothing is processed.
- Deprecated: use POST /v1/companies/{company_id}/products/bulk, 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/bulk
Request
- Base URL: https://app.beel.es/api
- URL: https://app.beel.es/api/v1/products/bulk
- 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.
| Status | Code | When |
|---|---|---|
| 400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
| 409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key. |
| 409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
Request body
Example request
{
"products": [
{
"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
Request processed. Always 201 when the batch was processed, even if not a single product could be created: the status code says whether the request was understood and run, not whether every row went well. The per-row split is in the report.
Example response
{
"success": true,
"data": {
"metadata": {
"total_products": 10,
"operation": "CREATE_PRODUCTS"
},
"products_creation": [
{
"code": "PROD-001",
"name": "Consultoría",
"status": "CREATED",
"product_id": "550e8400-e29b-41d4-a716-446655440000",
"error": {
"code": "PRODUCT_DUPLICATE",
"message": "A product with code 'PROD-001' already exists"
}
}
],
"statistics": {
"total_processed": 10,
"created": 8,
"duplicates": 1,
"invalid": 1
},
"created_products": [
{
"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.