Products
Create a product
Create a new product in your catalog.
post/companies/{company}/products
Request
- Base URL: https://api.factuarea.com/v1
- URL: https://api.factuarea.com/v1/companies/{company}/products
- Auth: one of:
- HTTP bearer
- API key in header X-API-Key
Path parameters
companystring uuid required
Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).
Headers
Idempotency-Keystring
Example:01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b
Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.
Factuarea-Versionstring date
Example:2026-06-01
Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.
Request body
Example request
{
"metadata": {
"erp_code": "IVA-GEN",
"ledger_account": "477000"
}
}Response
Product created successfully. The Location header contains the canonical URL of the newly created resource.
Example response
{
"data": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"object": "product",
"name": "Vino tinto D.O. Rioja",
"sku": "VINO-RIOJA",
"price": "1234.56",
"currency": "EUR",
"tax_rate": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
"rate": 21
},
"stock": "120.0000",
"gross_weight_kg": "0.9200",
"gallery": [
{
"index": 0,
"url": "https://files.factuarea.com/products/vino-rioja-garrafa.jpg",
"content_type": "image/jpeg"
}
],
"video": {
"url": "https://files.factuarea.com/products/vino-rioja-bodega.mp4",
"content_type": "video/mp4"
},
"is_active": true,
"description": "Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.",
"tags": [
"bodega",
"granel"
],
"low_stock_threshold": "10.0000",
"presentation_count": 1,
"variant_count": 1,
"supplier_offer_count": 1,
"option_group_count": 1,
"configuration_count": 1,
"preferred_supplier_offer_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20",
"presentations": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",
"object": "product_presentation",
"product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"name": "Garrafa de 5 L",
"mode": "fixed",
"unit": "LTR",
"conversion_factor": "5.000000",
"nominal_base_quantity": "5.0000",
"barcode": "8437012345678",
"gross_weight_kg": "4.8500",
"commercial_price_override": "18.5000",
"specifications": {
"envase": "PET alimentario",
"tapon": "Con grifo dosificador"
},
"active": true
}
],
"variants": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22",
"object": "product_variant",
"product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"name": "Superior",
"sku": "VINO-RIOJA-SUP",
"barcode": "8437012345685",
"base_price_override": "3.90",
"unit_cost_override": "2.40",
"gross_weight_kg": "0.9500",
"manage_stock": true,
"stock": "25.0000",
"low_stock_threshold": "5.0000",
"specifications": {
"crianza": "12 meses en barrica"
},
"active": true
}
],
"supplier_offers": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20",
"object": "supplier_product_offer",
"product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"supplier_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
"variant_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22",
"supplier_sku": "BOD-RIOJA-SUP",
"purchase_unit": "LTR",
"conversion_factor": "1.000000",
"unit_cost": "2.40",
"currency": "EUR",
"availability": "in_stock",
"minimum_quantity": "50.0000",
"lead_time_days": 3,
"preferred": true,
"active": true
}
],
"option_groups": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30",
"object": "product_option_group",
"product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"name": "Calidad",
"required": true,
"active": true,
"values": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31",
"object": "product_option_value",
"name": "Superior",
"position": 1,
"price_adjustment": "2.0000",
"active": true
}
]
}
],
"configurations": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40",
"object": "product_configuration",
"product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09",
"name": "Superior · Garrafa de 5 L · Calidad: Superior",
"variant_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22",
"variant_name": "Superior",
"presentation_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",
"presentation_name": "Garrafa de 5 L",
"signature": "b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f",
"commercial_price": "21.5000",
"active": true,
"options": [
{
"object": "product_configuration_option",
"group_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30",
"group_name": "Calidad",
"value_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31",
"value_name": "Superior",
"price_adjustment": "2.0000"
}
]
}
],
"is_in_stock": true,
"specifications": {
"origen": "España",
"denominacion": "D.O. Rioja",
"graduacion": "13,5 %"
},
"metadata": {
"erp_code": "IVA-GEN",
"ledger_account": "477000"
},
"external_id": "SHOP-42",
"created_at": "2026-01-02T08:30:00Z",
"updated_at": "2026-01-02T08:30:00Z",
"base_unit_change": {
"mode": "replacement",
"blockers": [
{
"code": "stock",
"quantity": "5",
"unit": "KGM"
},
{
"code": "movements",
"quantity": "22",
"unit": null
}
]
},
"replaces": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
"name": "Jamón ibérico al corte",
"base_unit": "GRM",
"replaced_at": "2026-10-15T09:30:00Z",
"equivalence": "0.001000",
"stock_transferred": "5000.0000"
},
"replaced_by": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
"name": "Jamón ibérico al corte",
"base_unit": "GRM",
"replaced_at": "2026-10-15T09:30:00Z",
"equivalence": "0.001000",
"stock_transferred": "5000.0000"
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.