Preview a base unit replacement

Compute, without writing anything, what happens when a product is replaced by a new one with a different base unit, and mint the impact_token that confirms THAT exact change.

The base unit of a product with history (stock, movements, presentations, supplier offers or variants with stock) cannot be edited in place: its base_unit_change.mode is replacement and the way to change it is to replace the product.
It is a READ — asking twice over the same catalog returns the same token — but it requires products:write, because the only thing its answer does is authorise an irreversible write.
Send target_base_unit (one of the nine measure units; a packaging unit such as XPK or XBX can only be a presentation), equivalence (how many units of the CURRENT base equal ONE unit of the NEW base, e.g. 0.001 when moving from kg to g because 1 g = 0.001 kg; required between a count unit and a measure unit, in either direction; calculated by itself inside the same measure family; there is none between two different measure families), an optional base_price to confirm, and presentations with a keep or retire decision per presentation of the old product (the ones you omit get the proposed decision).
The answer lists every element of the plan in items, each with its before, its after, its group (review, converted or carried) and its flags (precision_loss, no_equivalence, fraction); items[].ref is the public id of the affected element, and null for the product itself and for price-list entries and pack components, which have no public id.
pending_documents lists the unissued sales documents that will keep pointing at the old product.
The token is a fingerprint of the plan, not a credential: if the catalog, the price lists or the packs change before you confirm, the confirmation is rejected with 422 base_unit_replacement_preview_stale and you ask for a fresh preview.
A product of another company returns 404 product_not_found.

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

Base unit of the new product. Only the nine measure units are accepted: a packaging unit (XPK, XBX…) can only be a presentation unit.

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

equivalence?|

Units of the CURRENT base that equal ONE unit of the NEW base (moving from kg to g, 1 g = 0.001 kg, so 0.001; from kg to count units, 1 unit = 0.5 kg gives 0.5). Required between a count unit and a measure unit; inside the same measure family it is calculated and between two different measure families there is none.

Formatdecimal-6

Rangevalue <= 1000000000000

base_price?|

Base price of the new product per its base unit. Confirm it when the conversion loses precision or there is no equivalence.

Formatdecimal-2

Range0 <= value <= 99999999.99

presentations?array<>

Decision per presentation of the product being replaced. Presentations you omit get the proposed decision.

Itemsitems <= 500

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/preview", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json"} },  body: JSON.stringify({  "target_base_unit": "C62",  "equivalence": 0.25,  "base_price": 3,  "presentations": [    {      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",      "decision": "keep"    }  ]}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": {
    "object": "base_unit_replacement_preview",
    "product_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10",
    "from_base_unit": "KGM",
    "to_base_unit": "GRM",
    "equivalence": "0.001000",
    "equivalence_calculated": true,
    "price_confirmation_required": true,
    "items": [
      {
        "kind": "stock",
        "group": "converted",
        "ref": null,
        "name": null,
        "before": {
          "quantity": "5.0000",
          "unit_code": "KGM"
        },
        "after": {
          "quantity": "5000.0000",
          "unit_code": "GRM"
        },
        "flags": [],
        "decision": null,
        "proposed_decision": null
      },
      {
        "kind": "base_price",
        "group": "review",
        "ref": null,
        "name": null,
        "before": {
          "price": "38.00",
          "unit_code": "KGM"
        },
        "after": {
          "price": "0.04",
          "unit_code": "GRM"
        },
        "flags": [
          "precision_loss"
        ],
        "decision": null,
        "proposed_decision": null
      },
      {
        "kind": "presentation",
        "group": "review",
        "ref": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21",
        "name": "Pieza entera",
        "before": {
          "unit_code": "XPK",
          "mode": "fixed",
          "conversion_factor": "7.500000",
          "nominal_base_quantity": "7.5000",
          "price": "285.0000"
        },
        "after": {
          "unit_code": "XPK",
          "mode": "fixed",
          "conversion_factor": "7500.000000",
          "nominal_base_quantity": "7500.0000",
          "price": "285.0000"
        },
        "flags": [],
        "decision": "keep",
        "proposed_decision": "keep"
      }
    ],
    "pending_documents": [
      {
        "type": "quote",
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01",
        "number": "PRE-2026-0007",
        "status": "draft"
      }
    ],
    "impact_token": "9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"
  }
}

{
  "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 equivalencia debe ser un número positivo con hasta 6 decimales.",
    "param": "equivalence",
    "subcode": "base_unit_replacement_equivalence_invalid",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_d47d2a112832d0000000000000"
  }
}

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

Preview a base unit replacement

Authorization

Path Parameters

Headers

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Preview a base unit replacement

Authorization

Path Parameters

Headers

Request Body

Response Body

200application/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`