> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capcells.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a new version

> Change the terms by writing the next version whole. Every earlier version stays readable, and no issued loan moves.

A configuration is never edited: a change is the next version, stated whole. The body is the values alone — the Archetype and the identifier were fixed at creation, and the path names the configuration — and the same frame checks apply, [as at creation](/api-reference/product-configurations/create). [Try the body first](/api-reference/product-configurations/preview-version): the preview takes it, runs these checks, and writes nothing.

<Warning>
  A new version does not reach an issued Loan. Its Schedule, its amounts and its disclosed cost figure were priced at issuance, and nothing recomputes them. New issuances name the new version explicitly — `configuration_version` is always pinned.
</Warning>

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy writing.
</ParamField>

<ParamField path="id" type="string" required>
  The configuration the version belongs to.
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="string">
  Your own value, up to 255 bytes. This route carries no reference of yours, so the key is what makes a retry safe: the first outcome — refusals included — is recorded and answers every identical repeat for 24 hours, marked `Idempotent-Replayed: true`. The same key with a different request is <Badge color="orange">422</Badge> `idempotency_mismatch`.

  It is the fifth line of the signed canonical string, so sign with the key you send. [Retries](/api-reference/overview) carries the whole rule.
</ParamField>

## Body

<ParamField body="values" type="object" required>
  The terms, whole — every field the frame requires, restated. A version is not a diff: what it does not state, it does not have.
</ParamField>

## Response

`201` with the stored configuration at its new `version`, counting from 1 and rising by one, with `effective` beside `values` and the `advisories` the body earns — [as creation answers them](/api-reference/product-configurations/create#response). An advisory refuses nothing.

## Refusals

Everything [creation refuses](/api-reference/product-configurations/create), plus a body naming `archetype` — the shape never changes.

<RequestExample>
  ```bash Write version 2 theme={null}
  BODY='{
    "values": {
      "principal_min": { "minor_units": 100000, "currency": "MXN" },
      "principal_max": { "minor_units": 2000000, "currency": "MXN" },
      "rate_min": "36",
      "rate_max": "60",
      "penalty_rate_min": "36",
      "penalty_rate_max": "90",
      "day_count_basis": "actual_360",
      "schedule": { "kind": "anchored_monthly" },
      "terms": [6, 12, 18],
      "origination_fee": { "minor_units": 25000, "currency": "MXN" },
      "late_fee": { "minor_units": 20000, "currency": "MXN" }
    }
  }'

  IDEMPOTENCY_KEY="$(uuidgen)"

  curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/product-configurations/inst-000001/versions" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/product-configurations/inst-000001/versions" "$BODY" "$IDEMPOTENCY_KEY")" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "inst-000001",
    "tenant_id": "t-0001",
    "archetype": "instalment",
    "created_at": "2026-08-18T22:26:41.407349Z",
    "version": 2,
    "values": {
      "principal_min": { "minor_units": 100000, "currency": "MXN" },
      "principal_max": { "minor_units": 2000000, "currency": "MXN" },
      "rate_min": "36",
      "rate_max": "60",
      "penalty_rate_min": "36",
      "penalty_rate_max": "90",
      "day_count_basis": "actual_360",
      "origination_fee": { "minor_units": 25000, "currency": "MXN" },
      "late_fee": { "minor_units": 20000, "currency": "MXN" },
      "terms": [6, 12, 18],
      "schedule": { "kind": "anchored_monthly" }
    }
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.