Replace a product by changing its base unit

Replace a product by a NEW one with a different base unit and answer 201 with the new product, whose replaces points at the old one.

The stock, the presentations you keep, the variants, the supplier offers, the price-list entries and the pack components are converted and moved to the new product; the old one is deactivated, keeps its whole history and its replaced_by points at the new one, and it can never be reactivated.
It is IRREVERSIBLE: there is no inverse operation, so Idempotency-Key is mandatory and retrying with the same key returns the same response without creating a second product.
The body is the one of the preview plus the mandatory impact_token of a current preview with the same request.
It does not consume plan quota: the old product stops counting and the net usage is zero.
When the conversion loses precision or there is no equivalence, base_price must be confirmed (422 base_unit_replacement_price_confirmation_required).
Rejections: 422 business_rule_violation with subcode product_already_replaced, base_unit_replacement_conversion_unavailable or base_unit_replacement_blocked_by_packs; 422 parameter_invalid_value with subcode base_unit_replacement_same_unit (the target is already the base unit of the product), base_unit_replacement_equivalence_invalid, base_unit_replacement_price_confirmation_required, base_unit_replacement_preview_stale or base_unit_replacement_decision_invalid.
The product.replaced event is published with the new product as its object.
A product of another company returns 404 product_not_found.

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 409 idempotency_key_reused. See the Idempotency guide. Required on this operation: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with 422 idempotency_key_required before any business logic runs.

Length1 <= length <= 255

Factuarea-Version?string

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.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

target_base_unit*string

Value in"C62" | "KGM" | "GRM" | "LTR" | "MLT" | "MTR" | "MTK" | "HUR" | "DAY"

equivalence?|

Rangevalue <= 1000000000000

base_price?|

Range0 <= value <= 99999999.99

presentations?array<>

Itemsitems <= 500

impact_token*string

Match^[0-9a-fA-F]+$

Length64 <= length <= 64

Response Body

`application/json`

Request example

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/products/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/base_unit_replacement", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-products-base_unit_replacement-create"} },  body: JSON.stringify({  "target_base_unit": "C62",  "equivalence": 0.25,  "base_price": 3,  "presentations": [    {      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",      "decision": "keep"    }  ],  "impact_token": "9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01",
    "object": "product",
    "name": "Jamón ibérico al corte",
    "sku": "JAMON-IBERICO-G",
    "price": "0.04",
    "currency": "EUR",
    "tax_rate": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
      "rate": 21
    },
    "stock": "5000.0000",
    "item_kind": "product",
    "base_unit": "GRM",
    "gross_weight_kg": null,
    "manage_stock": true,
    "gallery": [],
    "video": null,
    "is_active": true,
    "description": "Jamón ibérico cortado a mano, vendido por gramos.",
    "tags": [],
    "low_stock_threshold": null,
    "presentation_count": 1,
    "variant_count": 0,
    "supplier_offer_count": 0,
    "option_group_count": 0,
    "configuration_count": 0,
    "catalog_availability_mode": "open",
    "preferred_supplier_offer_id": null,
    "presentations": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b31",
        "object": "product_presentation",
        "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01",
        "name": "Pieza entera",
        "mode": "fixed",
        "unit": "XPK",
        "conversion_factor": "7500.000000",
        "nominal_base_quantity": "7500.0000",
        "barcode": null,
        "commercial_price_override": "285.0000",
        "gross_weight_kg": null,
        "specifications": {},
        "active": true
      }
    ],
    "variants": [],
    "supplier_offers": [],
    "option_groups": [],
    "configurations": [],
    "is_low_stock": false,
    "is_in_stock": true,
    "specifications": {},
    "metadata": {},
    "external_id": null,
    "created_at": "2026-10-15T09:30:00Z",
    "updated_at": "2026-10-15T09:30:00Z",
    "base_unit_change": {
      "mode": "direct",
      "blockers": []
    },
    "replaces": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
      "name": "Jamón ibérico al corte",
      "base_unit": "KGM",
      "replaced_at": "2026-10-15T09:30:00Z",
      "equivalence": "0.001000",
      "stock_transferred": "5000.0000"
    },
    "replaced_by": null
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_308b24d41b5789477addf0a67f"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_54d11474e8a516d8cef78d336d"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "product_not_found",
    "message": "Producto no encontrado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#product_not_found",
    "request_id": "req_6cb2f9a0bca3bbd0994f378441"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_f663c95ab6217df04ccecfd1ac"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_value",
    "message": "La vista previa ya no corresponde al estado actual del producto o a esta petición, así que no se ha cambiado nada. Vuelve a solicitar la vista previa y confirma de nuevo.",
    "param": "impact_token",
    "subcode": "base_unit_replacement_preview_stale",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_909185bad8ac80000000000000"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_d291e3e4dbb43cb492bc7c0e1c"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_32a09e16361bd829d9db82948b"
  }
}

Replace a product by changing its base unit

Authorization

Path Parameters

Headers

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Replace a product by changing its base unit

Authorization

Path Parameters

Headers

Request Body

Response Body

201application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`