Price Formulas

Endpointhttps://api.kontier.eu/v1

Price formulas let you define dynamic pricing using mathematical expressions that are evaluated at billing time. This is useful for pricing models that depend on runtime variables - usage volume, contract size, exchange rates, or custom metrics.

Formulas support standard arithmetic operators, conditional logic, and named variables. Each variable has a type and optional default value. At billing time, the formula engine resolves all variables and computes the final price.

Example: base_price * (1 - volume_discount) where volume_discount increases with usage.

deprecated

List formula inputs

GET

https://api.kontier.eu/v1

/price-formula-inputs

Deprecated: use GET /price-formulas/inputs instead. Removed on 2026-11-30.

Lists the inputs the formula engine binds — quantity, tier_quantity, key, cost., sale_gross, product_price, plan_price — with each one's value type and the price layers whose formulas may read it. A caller never supplies one of these as a variable.

Required scope: price.read (Read prices).

List formula inputs › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List formula inputs › Responses

array | null · required

object · required

List price formulas

GET

https://api.kontier.eu/v1

/price-formulas

Lists price formulas with cursor-based pagination.

Required scope: price.read (Read prices).

List price formulas › query Parameters

include

string[] · explode: true

Extra data to add to the response: scheduled_versions. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. scheduled_versions is sent without being asked until 2026-11-30; after that date it is sent only when named here.

Enum values:

scheduled_versions

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

has_scheduled_version

string

Filter by whether the entity has a version scheduled to publish (true or false). A scheduled version is a FROZEN version row a pending catalog.publish_version Change is bound to; the entity itself stays draft, published or archived and its working draft stays free for immediate changes.

List price formulas › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List price formulas › Responses

array | null · required

object · required

GET/price-formulas

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "expression": "expression",
      "head_version": {
        "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
        "number": 0,
        "status": "draft"
      },
      "head_version_id": "0e79e2bb-bae6-5797-88cf-f4db7a41dfbd",
      "id": "8e969ca7-1b5d-5fe1-ad6d-8eea3909fc4f",
      "is_system": true,
      "lifecycle": "draft",
      "name": "name",
      "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
      "scheduled_versions": [
        {
          "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
          "change_id": "77c47428-5d7e-5acd-8dd2-1d6ed173809f",
          "scheduled_for": "2024-08-25T15:00:00Z",
          "version": 0,
          "version_id": "9543dded-6d98-5cc0-bc7e-3647a144dd9b"
        }
      ],
      "status": "draft",
      "updated_at": "2024-08-25T15:00:00Z",
      "variables": [
        {
          "default": "10",
          "name": "name",
          "type": "number"
        }
      ],
      "version": 0
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a price formula

POST

https://api.kontier.eu/v1

/price-formulas

Creates a price formula with a validated expression. The formula starts as a draft: a price can use it once its first version is published.

Required scope: price.write (Write prices).

Create a price formula › query Parameters

include

string[] · explode: true

Enum values:

scheduled_versions

Create a price formula › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a price formula › Request Body

expression

string · maxLength: 10000 · required

The expression to evaluate for a tier rate; may reference declared variables, cost., and lookup()/bracket() rate-table calls.

Example: cost.icann_fee * 1.15

name

string · maxLength: 200 · required

Display name for the formula.

array | null · maxItems: 100

Variables the expression references, each with a name, type, and optional default.

Create a price formula › Responses

Created

object · required

POST/price-formulas

curl --request POST \
  --url https://api.kontier.eu/v1/price-formulas \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "expression": "cost.icann_fee * 1.15",
  "name": "name",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

{
  "expression": "cost.icann_fee * 1.15",
  "name": "name",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "expression": "expression",
    "head_version": {
      "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
      "number": 0,
      "status": "draft"
    },
    "head_version_id": "0e79e2bb-bae6-5797-88cf-f4db7a41dfbd",
    "id": "8e969ca7-1b5d-5fe1-ad6d-8eea3909fc4f",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "scheduled_versions": [
      {
        "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
        "change_id": "77c47428-5d7e-5acd-8dd2-1d6ed173809f",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "9543dded-6d98-5cc0-bc7e-3647a144dd9b"
      }
    ],
    "status": "draft",
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": [
      {
        "default": "10",
        "name": "name",
        "type": "number"
      }
    ],
    "version": 0
  }
}

json

application/json

List formula inputs

GET

https://api.kontier.eu/v1

/price-formulas/inputs

Required scope: price.read (Read prices).

List formula inputs › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List formula inputs › Responses

array | null · required

object · required

Preview a price formula

POST

https://api.kontier.eu/v1

/price-formulas/preview

Evaluates a formula with variable bindings and changes nothing. Send either an inline expression or the id of a stored formula (its declared defaults apply under the bindings you send). Rate-table lookups read the rates in force now. Pass debug=true for a step-by-step trace.

Required scope: price.read (Read prices).

Preview a price formula › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Preview a price formula › Request Body

debug

boolean

When true, the response includes a step-by-step evaluation trace.

expression

string · maxLength: 10000

Ad-hoc expression to evaluate; either this or formula_id is required.

Example: cost.icann_fee * 1.15

formula_id

string · uuid

A stored formula to evaluate; either this or expression is required.

Example: 5ee4f4ef-4efd-5717-a74b-cc09591c8385

object

Variable bindings supplied to the evaluation, keyed by variable name: a number (or a decimal string) for a numeric variable, text for a string one.

Preview a price formula › Responses

object · required

POST/price-formulas/preview

curl --request POST \
  --url https://api.kontier.eu/v1/price-formulas/preview \
  --header 'Content-Type: application/json' \
  --data '
{
  "debug": true,
  "expression": "cost.icann_fee * 1.15",
  "formula_id": "5ee4f4ef-4efd-5717-a74b-cc09591c8385",
  "variables": {
    "key": {}
  }
}
'

shell

Example Request Body

{
  "debug": true,
  "expression": "cost.icann_fee * 1.15",
  "formula_id": "5ee4f4ef-4efd-5717-a74b-cc09591c8385",
  "variables": {
    "key": {}
  }
}

json

Example Responses

{
  "data": {
    "debug_trace": [
      {
        "expression": "expression",
        "node_type": "node_type",
        "position": 0,
        "result": "result"
      }
    ],
    "expression": "expression",
    "formula_id": "5ee4f4ef-4efd-5717-a74b-cc09591c8385",
    "formula_version": 0,
    "result": "10",
    "string_variables": {
      "key": "string"
    },
    "variables": {
      "key": "10"
    }
  }
}

json

application/json

Get a price formula

GET

https://api.kontier.eu/v1

/price-formulas/{id}

Returns a single price formula (expression plus variable definitions) by ID.

Required scope: price.read (Read prices).

Get a price formula › path Parameters

id

string · uuid · required

Price formula UUID

Get a price formula › query Parameters

include

string[] · explode: true

Enum values:

scheduled_versions

Get a price formula › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a price formula › Responses

object · required

GET/price-formulas/{id}

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "expression": "expression",
    "head_version": {
      "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
      "number": 0,
      "status": "draft"
    },
    "head_version_id": "0e79e2bb-bae6-5797-88cf-f4db7a41dfbd",
    "id": "8e969ca7-1b5d-5fe1-ad6d-8eea3909fc4f",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "scheduled_versions": [
      {
        "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
        "change_id": "77c47428-5d7e-5acd-8dd2-1d6ed173809f",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "9543dded-6d98-5cc0-bc7e-3647a144dd9b"
      }
    ],
    "status": "draft",
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": [
      {
        "default": "10",
        "name": "name",
        "type": "number"
      }
    ],
    "version": 0
  }
}

json

application/json

Delete a price formula

DELETE

https://api.kontier.eu/v1

/price-formulas/{id}

Deletes a price formula and archives its versions. A built-in formula cannot be deleted (409). Publishing a product version whose price still names the deleted formula is refused.

Required scope: price.write (Write prices).

Delete a price formula › path Parameters

id

string · uuid · required

Price formula UUID

Delete a price formula › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a price formula › Responses

No Content

No data returned

Update a price formula

PATCH

https://api.kontier.eu/v1

/price-formulas/{id}

Updates a price formula. A new name applies at once. A new expression or new variables are validated and go into the formula's working draft; they price nothing until that draft is published. The answer shows the formula in force.

Required scope: price.write (Write prices).

Update a price formula › path Parameters

id

string · uuid · required

Price formula UUID

Update a price formula › query Parameters

include

string[] · explode: true

Enum values:

scheduled_versions

Update a price formula › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a price formula › Request Body

expression

string · maxLength: 10000

New expression; omit to leave unchanged.

name

string · maxLength: 200

New display name; omit to leave unchanged.

array | null · maxItems: 100

Replacement variable declarations; omit to leave unchanged.

Update a price formula › Responses

object · required

PATCH/price-formulas/{id}

curl --request PATCH \
  --url https://api.kontier.eu/v1/price-formulas/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "expression": "expression",
  "name": "name",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

{
  "expression": "expression",
  "name": "name",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "expression": "expression",
    "head_version": {
      "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
      "number": 0,
      "status": "draft"
    },
    "head_version_id": "0e79e2bb-bae6-5797-88cf-f4db7a41dfbd",
    "id": "8e969ca7-1b5d-5fe1-ad6d-8eea3909fc4f",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "scheduled_versions": [
      {
        "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
        "change_id": "77c47428-5d7e-5acd-8dd2-1d6ed173809f",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "9543dded-6d98-5cc0-bc7e-3647a144dd9b"
      }
    ],
    "status": "draft",
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": [
      {
        "default": "10",
        "name": "name",
        "type": "number"
      }
    ],
    "version": 0
  }
}

json

application/json

Get the open working draft

GET

https://api.kontier.eu/v1

/price-formulas/{id}/draft

The entity's ONE working draft: its row id, the version it publishes as, when it was opened, the version it is authored on top of, and a counted summary of what is staged. data is null when nothing is staged — a state, not an error.

Required scope: price.read (Read prices).

Get the open working draft › path Parameters

id

string · uuid · required

Entity UUID

Get the open working draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the open working draft › Responses

object · required

Open the working draft on a chosen base

POST

https://api.kontier.eu/v1

/price-formulas/{id}/draft

Opens the working draft if none is open, and records which version it is authored on top of: the live head (omit base_version_id) or one of the entity's scheduled versions. Re-basing an open draft keeps its edits — the delta is the author's intent and is never rewritten — and re-materialises them over the new base. A publish of a draft based on a scheduled version cannot be scheduled to fire before that version does.

Required scope: price.write (Write prices).

Open the working draft on a chosen base › path Parameters

id

string · uuid · required

Entity UUID

Open the working draft on a chosen base › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Open the working draft on a chosen base › Request Body

base_version_id

string · uuid

The version the working draft is authored on top of — the live head, or one of the entity's scheduled versions. Omit for the head.

Example: a2414777-b019-5022-bcdc-3b7b71f5a162

Open the working draft on a chosen base › Responses

object · required

POST/price-formulas/{id}/draft

curl --request POST \
  --url https://api.kontier.eu/v1/price-formulas/:id/draft \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162"
}
'

shell

Example Request Body

{
  "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162"
}

json

Example Responses

{
  "data": {
    "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
    "created_at": "2024-08-25T15:00:00Z",
    "draft_version_id": "1adaada1-87b9-549e-b4d6-36ae64aba921",
    "release_name": "release_name",
    "release_note": "release_note",
    "summary": {
      "kinds": [
        {
          "count": 0,
          "kind": "kind"
        }
      ],
      "total": 0
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "updated_by": "3a69aa0c-e818-5b31-9650-90aa773df932",
    "version": 0
  }
}

json

application/json

Discard the open working draft

DELETE

https://api.kontier.eu/v1

/price-formulas/{id}/draft

Archives the working draft with reason 'discarded'. The live entity is untouched: nothing pointed at the draft and it was never on the billing timeline. 404 when nothing is staged, which is a different answer from a successful discard and is reported as one.

Required scope: price.write (Write prices).

Discard the open working draft › path Parameters

id

string · uuid · required

Entity UUID

Discard the open working draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Discard the open working draft › Responses

No Content

No data returned

Replace what the working draft contains

PUT

https://api.kontier.eu/v1

/price-formulas/{id}/draft/content

States what the draft should CONTAIN; the server derives the change against the draft's base and validates the result. A child the body omits is removed from the draft. Opens the working draft on the head when none is open.

Required scope: price.write (Write prices).

Replace what the working draft contains › path Parameters

id

string · uuid · required

Entity UUID

Replace what the working draft contains › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Replace what the working draft contains › Request Body

expression

string · maxLength: 10000 · required

The expression this version should evaluate.

array | null · maxItems: 100

The variables this version should declare, in the order they should be shown.

Replace what the working draft contains › Responses

object · required

PUT/price-formulas/{id}/draft/content

curl --request PUT \
  --url https://api.kontier.eu/v1/price-formulas/:id/draft/content \
  --header 'Content-Type: application/json' \
  --data '
{
  "expression": "expression",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

{
  "expression": "expression",
  "variables": [
    {
      "default": "10",
      "name": "name",
      "type": "number"
    }
  ]
}

json

Example Responses

{
  "data": {
    "base_version_id": "a2414777-b019-5022-bcdc-3b7b71f5a162",
    "created_at": "2024-08-25T15:00:00Z",
    "draft_version_id": "1adaada1-87b9-549e-b4d6-36ae64aba921",
    "release_name": "release_name",
    "release_note": "release_note",
    "summary": {
      "kinds": [
        {
          "count": 0,
          "kind": "kind"
        }
      ],
      "total": 0
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "updated_by": "3a69aa0c-e818-5b31-9650-90aa773df932",
    "version": 0
  }
}

json

application/json

List a price-formula's version timeline

GET

https://api.kontier.eu/v1

/price-formulas/{id}/timeline

The entity's versions in the order they fired and will fire: history, head, scheduled releases, working draft. Published and scheduled rows are returned by default; pass include=all for the draft and the archived rows. Same row shape as /versions.

Required scope: price.read (Read prices).

List a price-formula's version timeline › path Parameters

id

string · uuid · required

Entity UUID

List a price-formula's version timeline › query Parameters

include

string

Set to 'all' to include the working draft and archived rows.

limit

integer · min: 1

Page size (default 100, max 200)

Example: 50

cursor

string

List a price-formula's version timeline › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List a price-formula's version timeline › Responses

array | null · required

object · required

GET/price-formulas/{id}/timeline

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id/timeline

shell

Example Responses

{
  "data": [
    {
      "archived_reason": "archived_reason",
      "cascade_source": {
        "entity_id": "entity_id",
        "entity_kind": "entity_kind",
        "entity_name": "entity_name",
        "id": "id",
        "kind": "kind",
        "version": 0
      },
      "created_at": "2024-08-25T15:00:00Z",
      "diff": {
        "cascade": {
          "cost_key": "cost_key",
          "followed": {
            "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
            "name": "name",
            "version": 0
          },
          "followed_kind": "product",
          "source": "version"
        },
        "changes": [
          {
            "country_code": {
              "after": "after",
              "before": "before"
            },
            "currency": {
              "after": "EUR",
              "before": "EUR"
            },
            "dimensions": {
              "after": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "before": [
                {
                  "name": "name",
                  "value": "value"
                }
              ]
            },
            "display_name": {
              "after": "after",
              "before": "before"
            },
            "is_set_price": {
              "after": true,
              "before": true
            },
            "kind": "price_added",
            "list_price": {
              "after": "49.5",
              "before": "49.5"
            },
            "metadata": [
              {
                "after": "after",
                "before": "before",
                "key": "key"
              }
            ],
            "price": {
              "country_code": "country_code",
              "currency": "EUR",
              "dimensions": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "price_id": "be08ab19-172b-52cd-918c-709dce9fedd2",
              "price_key": "price_key"
            },
            "price_basis": {
              "after": "exclusive",
              "before": "exclusive"
            },
            "price_key": {
              "after": "after",
              "before": "before"
            },
            "product": {
              "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
              "name": "name",
              "version": 0
            },
            "tiers": {
              "after": [
                {
                  "basis": "per_unit",
                  "formula": {
                    "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                    "name": "name",
                    "version": 0
                  },
                  "formula_inputs": [
                    {
                      "name": "name",
                      "value": "value"
                    }
                  ],
                  "formula_policy": "latest",
                  "from": "10",
                  "package_size": "10",
                  "rate_expression": "rate_expression",
                  "unit_amount": "49.5",
                  "up_to": "10"
                }
              ],
              "before": [
                {
                  "basis": "per_unit",
                  "formula": {
                    "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                    "name": "name",
                    "version": 0
                  },
                  "formula_inputs": [
                    {
                      "name": "name",
                      "value": "value"
                    }
                  ],
                  "formula_policy": "latest",
                  "from": "10",
                  "package_size": "10",
                  "rate_expression": "rate_expression",
                  "unit_amount": "49.5",
                  "up_to": "10"
                }
              ]
            },
            "valid_from": {
              "after": "2024-08-25T15:00:00Z",
              "before": "2024-08-25T15:00:00Z"
            },
            "valid_to": {
              "after": "2024-08-25T15:00:00Z",
              "before": "2024-08-25T15:00:00Z"
            }
          }
        ],
        "entity_id": "87d9279d-3796-5830-890c-177a68bbad76",
        "from": {
          "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
          "number": 0,
          "status": "draft"
        },
        "kind": "product",
        "to": {
          "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
          "number": 0,
          "status": "draft"
        }
      },
      "effective_from": "2024-08-25T15:00:00Z",
      "effective_to": "2024-08-25T15:00:00Z",
      "id": "id",
      "origin": "manual",
      "published_at": "2024-08-25T15:00:00Z",
      "published_by": {
        "customer_id": "c4e24a5c-163a-5cf1-ac3e-d65f4b1528cc",
        "email": "email",
        "key_id": "0928eb68-2c74-5c75-9809-09d9a9f63263",
        "key_prefix": "key_prefix",
        "label": "label",
        "name": "name",
        "picture": "picture",
        "type": "user",
        "user_id": "user_id",
        "via": {
          "delegation_id": "1a6291f8-13b8-5e72-87c8-d496575506ca",
          "kind": "structural",
          "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
          "organization_name": "organization_name"
        }
      },
      "rank": 0,
      "recorded_at": "2024-08-25T15:00:00Z",
      "release_name": "release_name",
      "release_note": "release_note",
      "scheduled_change_id": "scheduled_change_id",
      "scheduled_for": "2024-08-25T15:00:00Z",
      "status": "draft",
      "usage_count": 0,
      "version": 0,
      "warnings": [
        {
          "field": "field",
          "message": "message",
          "type": "type"
        }
      ]
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

List price-formula versions

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions

Returns version rows for the entity, keyset-paginated (default 100, max 200 per page). The status filter accepts draft, scheduled, published, archived; the default excludes draft. include=usage_count adds how many records use each version; sort=version:desc lists the newest first.

Required scope: price.read (Read prices).

List price-formula versions › path Parameters

id

string · uuid · required

Entity UUID

List price-formula versions › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

status

string

Lifecycle status filter (repeatable / comma-separated): draft, scheduled, published, archived. Default excludes draft.

archived_reason

string

Narrow archived rows by reason (repeatable / comma-separated): canceled, discarded, errored, superseded

sort

string · enum

Order: version:asc (the default) lists the versions in the order they fired and will fire; version:desc lists the highest number first, versions without a number (the working draft, archived rows) last.

Enum values:

version:asc

version:desc

limit

integer · min: 1

Page size (default 100, max 200)

Example: 50

cursor

string

List price-formula versions › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List price-formula versions › Responses

array | null · required

object · required

GET/price-formulas/{id}/versions

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id/versions

shell

Example Responses

{
  "data": [
    {
      "archived_reason": "archived_reason",
      "cascade_source": {
        "entity_id": "entity_id",
        "entity_kind": "entity_kind",
        "entity_name": "entity_name",
        "id": "id",
        "kind": "kind",
        "version": 0
      },
      "created_at": "2024-08-25T15:00:00Z",
      "diff": {
        "cascade": {
          "cost_key": "cost_key",
          "followed": {
            "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
            "name": "name",
            "version": 0
          },
          "followed_kind": "product",
          "source": "version"
        },
        "changes": [
          {
            "country_code": {
              "after": "after",
              "before": "before"
            },
            "currency": {
              "after": "EUR",
              "before": "EUR"
            },
            "dimensions": {
              "after": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "before": [
                {
                  "name": "name",
                  "value": "value"
                }
              ]
            },
            "display_name": {
              "after": "after",
              "before": "before"
            },
            "is_set_price": {
              "after": true,
              "before": true
            },
            "kind": "price_added",
            "list_price": {
              "after": "49.5",
              "before": "49.5"
            },
            "metadata": [
              {
                "after": "after",
                "before": "before",
                "key": "key"
              }
            ],
            "price": {
              "country_code": "country_code",
              "currency": "EUR",
              "dimensions": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "price_id": "be08ab19-172b-52cd-918c-709dce9fedd2",
              "price_key": "price_key"
            },
            "price_basis": {
              "after": "exclusive",
              "before": "exclusive"
            },
            "price_key": {
              "after": "after",
              "before": "before"
            },
            "product": {
              "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
              "name": "name",
              "version": 0
            },
            "tiers": {
              "after": [
                {
                  "basis": "per_unit",
                  "formula": {
                    "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                    "name": "name",
                    "version": 0
                  },
                  "formula_inputs": [
                    {
                      "name": "name",
                      "value": "value"
                    }
                  ],
                  "formula_policy": "latest",
                  "from": "10",
                  "package_size": "10",
                  "rate_expression": "rate_expression",
                  "unit_amount": "49.5",
                  "up_to": "10"
                }
              ],
              "before": [
                {
                  "basis": "per_unit",
                  "formula": {
                    "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                    "name": "name",
                    "version": 0
                  },
                  "formula_inputs": [
                    {
                      "name": "name",
                      "value": "value"
                    }
                  ],
                  "formula_policy": "latest",
                  "from": "10",
                  "package_size": "10",
                  "rate_expression": "rate_expression",
                  "unit_amount": "49.5",
                  "up_to": "10"
                }
              ]
            },
            "valid_from": {
              "after": "2024-08-25T15:00:00Z",
              "before": "2024-08-25T15:00:00Z"
            },
            "valid_to": {
              "after": "2024-08-25T15:00:00Z",
              "before": "2024-08-25T15:00:00Z"
            }
          }
        ],
        "entity_id": "87d9279d-3796-5830-890c-177a68bbad76",
        "from": {
          "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
          "number": 0,
          "status": "draft"
        },
        "kind": "product",
        "to": {
          "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
          "number": 0,
          "status": "draft"
        }
      },
      "effective_from": "2024-08-25T15:00:00Z",
      "effective_to": "2024-08-25T15:00:00Z",
      "id": "id",
      "origin": "manual",
      "published_at": "2024-08-25T15:00:00Z",
      "published_by": {
        "customer_id": "c4e24a5c-163a-5cf1-ac3e-d65f4b1528cc",
        "email": "email",
        "key_id": "0928eb68-2c74-5c75-9809-09d9a9f63263",
        "key_prefix": "key_prefix",
        "label": "label",
        "name": "name",
        "picture": "picture",
        "type": "user",
        "user_id": "user_id",
        "via": {
          "delegation_id": "1a6291f8-13b8-5e72-87c8-d496575506ca",
          "kind": "structural",
          "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
          "organization_name": "organization_name"
        }
      },
      "rank": 0,
      "recorded_at": "2024-08-25T15:00:00Z",
      "release_name": "release_name",
      "release_note": "release_note",
      "scheduled_change_id": "scheduled_change_id",
      "scheduled_for": "2024-08-25T15:00:00Z",
      "status": "draft",
      "usage_count": 0,
      "version": 0,
      "warnings": [
        {
          "field": "field",
          "message": "message",
          "type": "type"
        }
      ]
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Get a price-formula version snapshot

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}

The version's own fields plus the common version header. {version} is the number, or the word 'draft' for the open working draft.

Required scope: price.read (Read prices).

Get a price-formula version snapshot › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

The version number, or the word 'draft' for the open working draft.

Get a price-formula version snapshot › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a price-formula version snapshot › Responses

object · required

GET/price-formulas/{id}/versions/{version}

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id/versions/:version

shell

Example Responses

{
  "data": {
    "archived_reason": "archived_reason",
    "base_version_id": "base_version_id",
    "cascade_source": {
      "entity_id": "entity_id",
      "entity_kind": "entity_kind",
      "entity_name": "entity_name",
      "id": "id",
      "kind": "kind",
      "version": 0
    },
    "created_at": "2024-08-25T15:00:00Z",
    "effective_from": "2024-08-25T15:00:00Z",
    "effective_to": "2024-08-25T15:00:00Z",
    "entity_id": "entity_id",
    "expression": "expression",
    "formula_id": "5ee4f4ef-4efd-5717-a74b-cc09591c8385",
    "id": "id",
    "is_system": true,
    "kind": "kind",
    "name": "name",
    "origin": "manual",
    "published_at": "2024-08-25T15:00:00Z",
    "published_by": {
      "customer_id": "c4e24a5c-163a-5cf1-ac3e-d65f4b1528cc",
      "email": "email",
      "key_id": "0928eb68-2c74-5c75-9809-09d9a9f63263",
      "key_prefix": "key_prefix",
      "label": "label",
      "name": "name",
      "picture": "picture",
      "type": "user",
      "user_id": "user_id",
      "via": {
        "delegation_id": "1a6291f8-13b8-5e72-87c8-d496575506ca",
        "kind": "structural",
        "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
        "organization_name": "organization_name"
      }
    },
    "rank": 0,
    "release_name": "release_name",
    "release_note": "release_note",
    "scheduled_change_id": "scheduled_change_id",
    "scheduled_for": "2024-08-25T15:00:00Z",
    "status": "draft",
    "variables": [
      {
        "default": "10",
        "name": "name",
        "type": "number"
      }
    ],
    "version": 0,
    "warnings": [
      {
        "field": "field",
        "message": "message",
        "type": "type"
      }
    ]
  }
}

json

application/json

Name or annotate a price-formula version

PATCH

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}

Sets the version's release_name and/or release_note. These are display metadata, not content: editing them never creates a new version and is allowed on published versions. An absent field is left unchanged; null clears it; an empty string is refused. It answers the version row without the data envelope; from 2026-11-30 it answers {"data": …} like every other operation.

Required scope: price.write (Write prices).

Name or annotate a price-formula version › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

The version number, or the word 'draft'.

Name or annotate a price-formula version › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Name or annotate a price-formula version › Request Body

release_name

string | null · minLength: 1 · maxLength: 120

New name; null clears it. Absent leaves it unchanged.

release_note

string | null · minLength: 1 · maxLength: 2000

New note; null clears it. Absent leaves it unchanged.

Name or annotate a price-formula version › Responses

created_at

string · date-time · required

When the row was opened — for a draft when editing started, for a release when it was armed.

effective_from

string | null · date-time · required

effective_to

string | null · date-time · required

id

string · required

The catalog_versions row id. A client selecting a version writes this, never the number.

origin

string · enum · required

Who made this version: manual (an operator published it), scheduled_release (a scheduled publish fired), cascade (republished automatically because something it depends on published).

Enum values:

manual

cascade

scheduled_release

published_at

string | null · date-time · required

status

string · enum · required

The row's own state: draft, scheduled, published or archived.

Enum values:

draft

scheduled

published

archived

version

integer · int64 · required

The version's display number, or 0 for a row that is not on the chain (a working draft, an archived row).

archived_reason

string

Why an archived row left the timeline: canceled, discarded or superseded.

object

For origin=cascade: what caused this version.

object

What the version does differently from the version it replaced; from is absent for the entity's first version. Sent only with include=diff (plans and products).

object

Who published the version — the same actor the audit trail names: an operator, an API key, or the system for a cascade. Absent on a version not yet published and on one published before publishers were recorded.

rank

integer · int64

1-based position in the entity's queue of scheduled versions — the order they will fire. Present only on scheduled rows.

recorded_at

string · date-time

When the publish was captured, on the wall clock (its audit row). published_at is the operation's instant — a sandbox's test clock — and effective_from when it governs. Sent with include=diff on published versions that have an audit row.

release_name

string

Operator-given name of this version, shown beside its number.

release_note

string

Free-text note about this version.

scheduled_change_id

string

The pending catalog.publish_version Change that will publish this version — reschedule or cancel it there.

scheduled_for

string · date-time

When this scheduled version is due to publish. Present only on a scheduled row.

usage_count

integer · int64

Present only with ?include=usage_count.

array | null

PATCH/price-formulas/{id}/versions/{version}

curl --request PATCH \
  --url https://api.kontier.eu/v1/price-formulas/:id/versions/:version \
  --header 'Content-Type: application/json' \
  --data '
{
  "release_name": "release_name",
  "release_note": "release_note"
}
'

shell

Example Request Body

{
  "release_name": "release_name",
  "release_note": "release_note"
}

json

Example Responses

{
  "archived_reason": "archived_reason",
  "cascade_source": {
    "entity_id": "entity_id",
    "entity_kind": "entity_kind",
    "entity_name": "entity_name",
    "id": "id",
    "kind": "kind",
    "version": 0
  },
  "created_at": "2024-08-25T15:00:00Z",
  "diff": {
    "cascade": {
      "cost_key": "cost_key",
      "followed": {
        "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
        "name": "name",
        "version": 0
      },
      "followed_kind": "product",
      "source": "version"
    },
    "changes": [
      {
        "country_code": {
          "after": "after",
          "before": "before"
        },
        "currency": {
          "after": "EUR",
          "before": "EUR"
        },
        "dimensions": {
          "after": [
            {
              "name": "name",
              "value": "value"
            }
          ],
          "before": [
            {
              "name": "name",
              "value": "value"
            }
          ]
        },
        "display_name": {
          "after": "after",
          "before": "before"
        },
        "is_set_price": {
          "after": true,
          "before": true
        },
        "kind": "price_added",
        "list_price": {
          "after": "49.5",
          "before": "49.5"
        },
        "metadata": [
          {
            "after": "after",
            "before": "before",
            "key": "key"
          }
        ],
        "price": {
          "country_code": "country_code",
          "currency": "EUR",
          "dimensions": [
            {
              "name": "name",
              "value": "value"
            }
          ],
          "price_id": "be08ab19-172b-52cd-918c-709dce9fedd2",
          "price_key": "price_key"
        },
        "price_basis": {
          "after": "exclusive",
          "before": "exclusive"
        },
        "price_key": {
          "after": "after",
          "before": "before"
        },
        "product": {
          "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
          "name": "name",
          "version": 0
        },
        "tiers": {
          "after": [
            {
              "basis": "per_unit",
              "formula": {
                "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                "name": "name",
                "version": 0
              },
              "formula_inputs": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "formula_policy": "latest",
              "from": "10",
              "package_size": "10",
              "rate_expression": "rate_expression",
              "unit_amount": "49.5",
              "up_to": "10"
            }
          ],
          "before": [
            {
              "basis": "per_unit",
              "formula": {
                "id": "6a0f275f-03c5-5905-95be-8d23982663a4",
                "name": "name",
                "version": 0
              },
              "formula_inputs": [
                {
                  "name": "name",
                  "value": "value"
                }
              ],
              "formula_policy": "latest",
              "from": "10",
              "package_size": "10",
              "rate_expression": "rate_expression",
              "unit_amount": "49.5",
              "up_to": "10"
            }
          ]
        },
        "valid_from": {
          "after": "2024-08-25T15:00:00Z",
          "before": "2024-08-25T15:00:00Z"
        },
        "valid_to": {
          "after": "2024-08-25T15:00:00Z",
          "before": "2024-08-25T15:00:00Z"
        }
      }
    ],
    "entity_id": "87d9279d-3796-5830-890c-177a68bbad76",
    "from": {
      "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
      "number": 0,
      "status": "draft"
    },
    "kind": "product",
    "to": {
      "id": "5999df64-8e0f-5f41-8604-f37d8225f570",
      "number": 0,
      "status": "draft"
    }
  },
  "effective_from": "2024-08-25T15:00:00Z",
  "effective_to": "2024-08-25T15:00:00Z",
  "id": "id",
  "origin": "manual",
  "published_at": "2024-08-25T15:00:00Z",
  "published_by": {
    "customer_id": "c4e24a5c-163a-5cf1-ac3e-d65f4b1528cc",
    "email": "email",
    "key_id": "0928eb68-2c74-5c75-9809-09d9a9f63263",
    "key_prefix": "key_prefix",
    "label": "label",
    "name": "name",
    "picture": "picture",
    "type": "user",
    "user_id": "user_id",
    "via": {
      "delegation_id": "1a6291f8-13b8-5e72-87c8-d496575506ca",
      "kind": "structural",
      "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
      "organization_name": "organization_name"
    }
  },
  "rank": 0,
  "recorded_at": "2024-08-25T15:00:00Z",
  "release_name": "release_name",
  "release_note": "release_note",
  "scheduled_change_id": "scheduled_change_id",
  "scheduled_for": "2024-08-25T15:00:00Z",
  "status": "draft",
  "usage_count": 0,
  "version": 0,
  "warnings": [
    {
      "field": "field",
      "message": "message",
      "type": "type"
    }
  ]
}

json

application/json

Compare two price-formula versions

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}/diff

Every cell that differs between two versions, with the value on each side. ?against= takes 'head' (the default), another version number, or 'draft'. The comparison is of the two versions' STORED grids — nothing is recomputed at read time.

Required scope: price.read (Read prices).

Compare two price-formula versions › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

The version number, or the word 'draft'.

Compare two price-formula versions › query Parameters

against

string

What to compare against: 'head' (the default) for the live version, or another version number, or 'draft'.

Compare two price-formula versions › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Compare two price-formula versions › Responses

object · required

Preview what else publishing this version would publish

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}/followers

The entities that will publish BECAUSE this one does — a plan that tracks this product's latest, say — each with the cells its next head would carry that its current one does not. Derived on every read and never frozen: something that starts following tomorrow appears tomorrow.

Required scope: price.read (Read prices).

Preview what else publishing this version would publish › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

The version number, or the word 'draft' for the open working draft.

Preview what else publishing this version would publish › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Preview what else publishing this version would publish › Responses

array | null · required

object · required

Forecast the impact of superseding this price-formula version

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}/publish-impact

Who is using the version in force today, and what a publish over it would move. pinnable reports whether holding a version is possible for this entity at all — it is false for tax rules, which are dated rather than pinned, so a caller must not render a pinned count for them. republishes_consumers is the cross-entity fan-out (publishing a price formula republishes every ACTIVE product whose head tiers reference it), and live_readers counts consumers billing off the live head, who move as soon as the publish lands. Read-only, and uncached: this is read at the moment money changes.

Required scope: price.read (Read prices).

Forecast the impact of superseding this price-formula version › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

Forecast the impact of superseding this price-formula version › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Forecast the impact of superseding this price-formula version › Responses

object · required

GET/price-formulas/{id}/versions/{version}/publish-impact

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id/versions/:version/publish-impact

shell

Example Responses

{
  "data": {
    "breakdown": {
      "applied_to_invoice_lines": 0,
      "direct_subscriptions": 0,
      "pinned_by_plans": 0,
      "pinned_by_prices": 0,
      "subscription_history": 0,
      "subscription_lines": 0,
      "used_in_invoice_atoms": 0,
      "used_in_invoice_lines": 0
    },
    "entity_id": "87d9279d-3796-5830-890c-177a68bbad76",
    "entity_type": "plan",
    "lifecycle": "lifecycle",
    "live_readers": 0,
    "pinnable": true,
    "republishes_consumers": 0,
    "total_referrers": 0,
    "version": 0
  }
}

json

application/json

List price-formula version referrers

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}/referrers

Offset-paginated drill-down of the referrers of one type for one version of the entity.

Required scope: price.read (Read prices).

List price-formula version referrers › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

List price-formula version referrers › query Parameters

type

string

Referrer type to list (required)

limit

integer · min: 1

Page size (default 50, max 200)

Example: 50

cursor

string

List price-formula version referrers › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List price-formula version referrers › Responses

array | null · required

object · required

GET/price-formulas/{id}/versions/{version}/referrers

curl --request GET \
  --url https://api.kontier.eu/v1/price-formulas/:id/versions/:version/referrers

shell

Example Responses

{
  "data": [
    {
      "created_at": "2024-08-25T15:00:00Z",
      "customer_id": "c4e24a5c-163a-5cf1-ac3e-d65f4b1528cc",
      "customer_name": "customer_name",
      "id": "f84fd291-8b38-50fe-9fb1-004f6dac9761",
      "invoice_id": "ad796aee-fbf8-5e97-b688-00f2ce03f034",
      "invoice_number": "invoice_number",
      "label": "label",
      "since": "2024-08-25T15:00:00Z",
      "sub_label": "sub_label",
      "type": "type"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Get price-formula version usage summary

GET

https://api.kontier.eu/v1

/price-formulas/{id}/versions/{version}/usage

Referrer counts for one version of the entity, grouped by referrer type. Powers the version-switcher hover card.

Required scope: price.read (Read prices).

Get price-formula version usage summary › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

Get price-formula version usage summary › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get price-formula version usage summary › Responses

object · required

Prices Rate Tables