Price Formulas

Endpointhttps://api.kontorion.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.kontorion.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.

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

Create a price formula

POST

https://api.kontorion.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

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

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.kontorion.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,
    "name": "name",
    "organization_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.kontorion.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

Delete a price formula

DELETE

https://api.kontorion.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.kontorion.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.

save_as_draft

boolean

When true, parks the new expression/variables in a draft version without advancing the live head; billing is unaffected until it is published.

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.kontorion.eu/v1/price-formulas/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "expression": "expression",
  "name": "name",
  "save_as_draft": true,
  "variables": [
    {
      "default": 0,
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

{
  "expression": "expression",
  "name": "name",
  "save_as_draft": true,
  "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,
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": {},
    "version": 0
  }
}

json

application/json

List price-formula versions (with lifecycle filter)

GET

https://api.kontorion.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.kontorion.eu/v1/price-formulas/:id/versions

shell

Example Responses

{
  "data": [
    {
      "archived_reason": "archived_reason",
      "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",
      "published_at": "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.kontorion.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

List price-formula version referrers

GET

https://api.kontorion.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

offset

string

Row offset (default 0)

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

Kontorion Billing API

Price Formulas

Endpointhttps://api.kontorion.eu/v1

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

List price formulas

GET

https://api.kontorion.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

List price formulas › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List price formulas › Responses

array | null · required

object · required

Create a price formula

POST

https://api.kontorion.eu/v1

/price-formulas

Creates a new price formula with a validated expression.

Create a price formula › Headers

Idempotency-Key

string · required

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

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

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.kontorion.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,
    "name": "name",
    "organization_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.kontorion.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

Delete a price formula

DELETE

https://api.kontorion.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.kontorion.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.

save_as_draft

boolean

When true, parks the new expression/variables in a draft version without advancing the live head; billing is unaffected until it is published.

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.kontorion.eu/v1/price-formulas/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "expression": "expression",
  "name": "name",
  "save_as_draft": true,
  "variables": [
    {
      "default": 0,
      "name": "name",
      "type": "number"
    }
  ]
}
'

shell

Example Request Body

{
  "expression": "expression",
  "name": "name",
  "save_as_draft": true,
  "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,
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "updated_at": "2024-08-25T15:00:00Z",
    "variables": {},
    "version": 0
  }
}

json

application/json

List price-formula versions (with lifecycle filter)

GET

https://api.kontorion.eu/v1

/price-formulas/{id}/versions

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.kontorion.eu/v1/price-formulas/:id/versions

shell

Example Responses

{
  "data": [
    {
      "archived_reason": "archived_reason",
      "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",
      "published_at": "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.kontorion.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

List price-formula version referrers

GET

https://api.kontorion.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

offset

string

Row offset (default 0)

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