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.

List price formulas

GET

https://api.kontier.eu/v1

/price-formulas

Lists price formulas with cursor-based pagination.

List price formulas › query Parameters

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

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 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": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_system": true,
      "lifecycle": "draft",
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "scheduled_versions": [
        {
          "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "change_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "scheduled_for": "2024-08-25T15:00:00Z",
          "version": 0,
          "version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
        }
      ],
      "updated_at": "2024-08-25T15:00:00Z",
      "variables": {},
      "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 new price formula with a validated expression.

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": 0,
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

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

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "expression": "expression",
    "head_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "scheduled_versions": [
      {
        "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "change_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": {},
    "version": 0
  }
}

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.

Get a price formula › path Parameters

id

string · uuid · required

Price formula UUID

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": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "scheduled_versions": [
      {
        "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "change_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": {},
    "version": 0
  }
}

json

application/json

Delete a price formula

DELETE

https://api.kontier.eu/v1

/price-formulas/{id}

Soft-deletes a price formula. Fails with 409 if the formula is still referenced by an active rate-table version.

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 an existing price formula by ID, re-validating the expression if changed.

Update a price formula › path Parameters

id

string · uuid · required

Price formula UUID

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": 0,
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

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

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "expression": "expression",
    "head_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_system": true,
    "lifecycle": "draft",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "scheduled_versions": [
      {
        "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "change_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "scheduled_for": "2024-08-25T15:00:00Z",
        "version": 0,
        "version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": {},
    "version": 0
  }
}

json

application/json

Get the staged draft

GET

https://api.kontier.eu/v1

/price-formulas/{id}/draft

The entity's open draft: its row id (the same id catalog.publish_version binds as staged_version_id), the version number it will publish as, when it was opened and last touched, the head version it forks from, and a counted summary of what is staged. 404 when nothing is staged — which is a state, not an error.

Get the staged draft › path Parameters

id

string · uuid · required

The entity's UUID

Get the staged draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the staged draft › Responses

object · required

Discard the staged draft

DELETE

https://api.kontier.eu/v1

/price-formulas/{id}/draft

Throws the staged draft away. 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.

Discard the staged draft › path Parameters

id

string · uuid · required

The entity's UUID

Discard the staged draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Discard the staged draft › Responses

No Content

No data returned

List price-formula versions (with lifecycle filter)

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 (ADR-0007). Supports ?include=usage_count and ?archived_reason=.

List price-formula versions (with lifecycle filter) › path Parameters

id

string · uuid · required

Entity UUID

List price-formula versions (with lifecycle filter) › query Parameters

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

include

string

Comma-separated includes. Currently supports usage_count.

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

List price-formula versions (with lifecycle filter) › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List price-formula versions (with lifecycle filter) › 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_name": "entity_name",
        "entity_type": "entity_type",
        "version": 0,
        "version_id": "version_id"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "created_by",
      "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",
      "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",
      "usage_count": 0,
      "version": 0,
      "warnings": [
        {
          "field": "field",
          "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}

Maps version-number → version-id via the adapter, then loads the full price_formula_version snapshot (expression + variables at that version).

Get a price-formula version snapshot › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number

Get a price-formula version snapshot › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a price-formula version snapshot › Responses

object · required

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; an empty string clears it.

Name or annotate a price-formula version › path Parameters

id

string · uuid · required

Entity UUID

version

integer · int64 · min: 1 · required

The version number

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 · maxLength: 120

New name; empty string clears it. Absent leaves it unchanged.

release_note

string · maxLength: 2000

New note; empty string clears it. Absent leaves it unchanged.

Name or annotate a price-formula version › Responses

created_at

string · date-time · required

effective_from

string | null · date-time · required

effective_to

string | null · date-time · required

id

string · required

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

scheduled_release

cascade

published_at

string | null · date-time · required

status

string · enum · required

Enum values:

draft

scheduled

published

archived

version

integer · int64 · required

archived_reason

string

object

For origin=cascade: the version whose publish caused this one, resolved to its entity and number.

created_by

string

rank

integer · int64

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

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 the row a pending catalog.publish_version Change is bound to.

usage_count

integer · int64

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_name": "entity_name",
    "entity_type": "entity_type",
    "version": 0,
    "version_id": "version_id"
  },
  "created_at": "2024-08-25T15:00:00Z",
  "created_by": "created_by",
  "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",
  "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",
  "usage_count": 0,
  "version": 0,
  "warnings": [
    {
      "field": "field",
      "type": "type"
    }
  ]
}

json

application/json

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.

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_items": 0,
      "used_in_invoice_atoms": 0,
      "used_in_invoice_lines": 0
    },
    "entity_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "entity_type": "entity_type",
    "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.

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. 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

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": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "customer_name": "customer_name",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "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.

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