Costs

Endpointhttps://api.kontorion.eu/v1

Product and org-scoped cost definitions consumed by pricing formulas.

List costs (org-wide)

GET

https://api.kontorion.eu/v1

/costs

Returns a paginated list of every active cost in the organization. Use scope=ORG to fetch only org-scoped costs (shared upstream fees) and scope=PRODUCT for the cross-product roll-up.

List costs (org-wide) › query Parameters

scope

string · enum

Filter by cost scope

Enum values:

ORG

PRODUCT

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 costs (org-wide) › 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 costs (org-wide) › Responses

array | null · required

object · required

GET/costs

curl --request GET \
  --url https://api.kontorion.eu/v1/costs

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create an org-scoped cost

POST

https://api.kontorion.eu/v1

/costs

Creates an ORG-scoped cost — used for shared upstream fees (payment processor, registry, etc.) that span multiple products.

Create an org-scoped cost › 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 an org-scoped cost › Request Body

object

Static money value; set exactly one of amount or expression.

description

string · maxLength: 2000

Operator-facing description of what this cost represents.

object

Formula referencing other costs by key; set exactly one of amount or expression.

key

string

Formula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].

object

Free-form operator key/value metadata.

product_id

string · uuid

Owning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Locale-keyed overrides for the cost's description.

Create an org-scoped cost › Responses

Created

object · required

POST/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/costs \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a cost

GET

https://api.kontorion.eu/v1

/costs/{id}

Scope-agnostic detail read: serves both PRODUCT- and ORG-scoped costs by cost id. Archived costs are not served.

Get a cost › path Parameters

id

string · uuid · required

Cost UUID

Get a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a cost › Responses

object · required

GET/costs/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/costs/:id

shell

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update a cost

PATCH

https://api.kontorion.eu/v1

/costs/{id}

Merge-patch update, scope-agnostic. Value changes (amount, expression) are versioned: they accept the effective_at / save_as_draft publish controls, and saving an ORG-scoped cost's value republishes every ACTIVE product consuming it (see /costs/{id}/consumers). Display-only edits (description, translations, metadata) apply immediately and reject publish controls.

Update a cost › path Parameters

id

string · uuid · required

Cost UUID

Update a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a cost › Request Body

object

Replacement static money value; set at most one of amount or expression.

description

string · maxLength: 2000

New operator-facing description; null leaves it unchanged.

effective_at

string · date-time

Schedule the change to take effect at this instant instead of applying immediately; mutually exclusive with save_as_draft.

object

Replacement formula referencing other costs by key; set at most one of amount or expression.

object

Free-form operator key/value metadata.

requires_continuous_coverage

boolean

Flips the continuous-coverage requirement live without touching the billing value; null leaves it unchanged.

save_as_draft

boolean

Persist the change as a working draft instead of applying it; mutually exclusive with effective_at.

object

Locale-keyed overrides for the cost's description.

Update a cost › Responses

object · required

PATCH/costs/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/costs/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "effective_at": "2024-08-25T15:00:00Z",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "metadata": {
    "key": {}
  },
  "requires_continuous_coverage": true,
  "save_as_draft": true,
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "effective_at": "2024-08-25T15:00:00Z",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "metadata": {
    "key": {}
  },
  "requires_continuous_coverage": true,
  "save_as_draft": true,
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Archive a cost (terminal)

POST

https://api.kontorion.eu/v1

/costs/{id}/archive

Terminally archives a cost (soft transition to status=archived): the value leaves billing at the next product publish. Returns 200 with the archived cost. There is no un-archive; create a new cost instead.

Archive a cost (terminal) › path Parameters

id

string · uuid · required

Cost UUID

Archive a cost (terminal) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Archive a cost (terminal) › Responses

object · required

POST/costs/{id}/archive

curl --request POST \
  --url https://api.kontorion.eu/v1/costs/:id/archive \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List products consuming a cost

GET

https://api.kontorion.eu/v1

/costs/{id}/consumers

The consumer census. For an ORG-scoped cost: every ACTIVE product whose head version materialized the cost's key. For a PRODUCT-scoped cost: the owning product.

List products consuming a cost › path Parameters

id

string · uuid · required

Cost UUID

List products consuming a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List products consuming a cost › Responses

array | null · required

object · required

List costs for a product

GET

https://api.kontorion.eu/v1

/products/{id}/costs

Lists the costs visible to one product. Values come from the published head by default; ?view=draft serves the product's open working-draft values, ?view=head restricts to published-only rows, and ?product_version_id pins values to one historical product version (mutually exclusive with view).

List costs for a product › path Parameters

id

string · uuid · required

Product UUID

List costs for a product › 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

view

string · enum

Value view: draft (working-draft values) or head (published only)

Enum values:

draft

head

product_version_id

string · uuid

Pin values to a product version

List costs for a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List costs for a product › Responses

array | null · required

object · required

GET/products/{id}/costs

curl --request GET \
  --url https://api.kontorion.eu/v1/products/:id/costs

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a product-scoped cost

POST

https://api.kontorion.eu/v1

/products/{id}/costs

Creates a PRODUCT-scoped cost owned by the product in the URL — the URL determines scope; use POST /costs for shared ORG-scoped costs. The value reaches billing when the product is next published.

Create a product-scoped cost › path Parameters

id

string · uuid · required

Product UUID

Create a product-scoped cost › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a product-scoped cost › Request Body

object

Static money value; set exactly one of amount or expression.

description

string · maxLength: 2000

Operator-facing description of what this cost represents.

object

Formula referencing other costs by key; set exactly one of amount or expression.

key

string

Formula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].

object

Free-form operator key/value metadata.

product_id

string · uuid

Owning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Locale-keyed overrides for the cost's description.

Create a product-scoped cost › Responses

Created

object · required

POST/products/{id}/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/products/:id/costs \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Promotions Key Sets

Kontorion Billing API

Costs

Endpointhttps://api.kontorion.eu/v1

Product and org-scoped cost definitions consumed by pricing formulas.

List costs (org-wide)

GET

https://api.kontorion.eu/v1

/costs

Returns a paginated list of every active cost in the organization. Use scope=ORG to fetch only org-scoped costs (shared upstream fees) and scope=PRODUCT for the cross-product roll-up.

List costs (org-wide) › query Parameters

scope

string · enum

Filter by cost scope

Enum values:

ORG

PRODUCT

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 costs (org-wide) › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List costs (org-wide) › Responses

array | null · required

object · required

GET/costs

curl --request GET \
  --url https://api.kontorion.eu/v1/costs

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create an org-scoped cost

POST

https://api.kontorion.eu/v1

/costs

Creates an ORG-scoped cost — used for shared upstream fees (payment processor, registry, etc.) that span multiple products.

Create an org-scoped cost › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create an org-scoped cost › Request Body

object

Static money value; set exactly one of amount or expression.

description

string · maxLength: 2000

Operator-facing description of what this cost represents.

object

Formula referencing other costs by key; set exactly one of amount or expression.

key

string

Formula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].

object

Free-form operator key/value metadata.

product_id

string · uuid

Owning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Locale-keyed overrides for the cost's description.

Create an org-scoped cost › Responses

Created

object · required

POST/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/costs \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a cost

GET

https://api.kontorion.eu/v1

/costs/{id}

Scope-agnostic detail read: serves both PRODUCT- and ORG-scoped costs by cost id. Archived costs are not served.

Get a cost › path Parameters

id

string · uuid · required

Cost UUID

Get a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a cost › Responses

object · required

GET/costs/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/costs/:id

shell

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Update a cost

PATCH

https://api.kontorion.eu/v1

/costs/{id}

Update a cost › path Parameters

id

string · uuid · required

Cost UUID

Update a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a cost › Request Body

object

Replacement static money value; set at most one of amount or expression.

description

string · maxLength: 2000

New operator-facing description; null leaves it unchanged.

effective_at

string · date-time

Schedule the change to take effect at this instant instead of applying immediately; mutually exclusive with save_as_draft.

object

Replacement formula referencing other costs by key; set at most one of amount or expression.

object

Free-form operator key/value metadata.

requires_continuous_coverage

boolean

Flips the continuous-coverage requirement live without touching the billing value; null leaves it unchanged.

save_as_draft

boolean

Persist the change as a working draft instead of applying it; mutually exclusive with effective_at.

object

Locale-keyed overrides for the cost's description.

Update a cost › Responses

object · required

PATCH/costs/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/costs/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "effective_at": "2024-08-25T15:00:00Z",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "metadata": {
    "key": {}
  },
  "requires_continuous_coverage": true,
  "save_as_draft": true,
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "effective_at": "2024-08-25T15:00:00Z",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "metadata": {
    "key": {}
  },
  "requires_continuous_coverage": true,
  "save_as_draft": true,
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Archive a cost (terminal)

POST

https://api.kontorion.eu/v1

/costs/{id}/archive

Archive a cost (terminal) › path Parameters

id

string · uuid · required

Cost UUID

Archive a cost (terminal) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Archive a cost (terminal) › Responses

object · required

POST/costs/{id}/archive

curl --request POST \
  --url https://api.kontorion.eu/v1/costs/:id/archive \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List products consuming a cost

GET

https://api.kontorion.eu/v1

/costs/{id}/consumers

The consumer census. For an ORG-scoped cost: every ACTIVE product whose head version materialized the cost's key. For a PRODUCT-scoped cost: the owning product.

List products consuming a cost › path Parameters

id

string · uuid · required

Cost UUID

List products consuming a cost › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List products consuming a cost › Responses

array | null · required

object · required

List costs for a product

GET

https://api.kontorion.eu/v1

/products/{id}/costs

List costs for a product › path Parameters

id

string · uuid · required

Product UUID

List costs for a product › 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

view

string · enum

Value view: draft (working-draft values) or head (published only)

Enum values:

draft

head

product_version_id

string · uuid

Pin values to a product version

List costs for a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List costs for a product › Responses

array | null · required

object · required

GET/products/{id}/costs

curl --request GET \
  --url https://api.kontorion.eu/v1/products/:id/costs

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a product-scoped cost

POST

https://api.kontorion.eu/v1

/products/{id}/costs

Creates a PRODUCT-scoped cost owned by the product in the URL — the URL determines scope; use POST /costs for shared ORG-scoped costs. The value reaches billing when the product is next published.

Create a product-scoped cost › path Parameters

id

string · uuid · required

Product UUID

Create a product-scoped cost › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a product-scoped cost › Request Body

object

Static money value; set exactly one of amount or expression.

description

string · maxLength: 2000

Operator-facing description of what this cost represents.

object

Formula referencing other costs by key; set exactly one of amount or expression.

key

string

Formula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].

object

Free-form operator key/value metadata.

product_id

string · uuid

Owning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

object

Locale-keyed overrides for the cost's description.

Create a product-scoped cost › Responses

Created

object · required

POST/products/{id}/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/products/:id/costs \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Promotions Key Sets