Costs

Endpointhttps://api.kontorion.eu/v1

List costs (org-wide)

GET

https://api.kontorion.eu/v1

/costs

Returns a paginated list of costs for the given product. Returns a paginated list of every active cost in the

List costs (org-wide) › query Parameters

limit

integer

Page size

cursor

string

Pagination cursor

scope

string · enum

Filter by cost scope

Enum values:

ORG

PRODUCT

limit

integer

Page size

cursor

string

Pagination cursor

List costs (org-wide) › Responses

Paginated list with data and pagination envelope

object[]

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

GET/costs

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

shell

Example Responses

{
  "key": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "archived_at",
      "created_at": "created_at",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "head_version_id": "head_version_id",
      "id": "id",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "organization_id",
      "product_id": "product_id",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "updated_at",
      "version": 0
    }
  ]
}

json

application/json

Create a cost

POST

https://api.kontorion.eu/v1

/costs

Creates a cost. When the route includes {productId}, the cost is PRODUCT-scoped to that product. The bare /costs route creates an ORG-scoped cost — used for shared upstream fees (payment processor, registry, etc.) that span multiple products.

Create a cost › Request Body

object

description

string

object

key

string

object

product_id

string

object

Create a cost › Responses

Created

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

POST/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/costs \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "product_id",
  "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": "product_id",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "archived_at": "archived_at",
  "created_at": "created_at",
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "head_version_id": "head_version_id",
  "id": "id",
  "key": "key",
  "metadata": {
    "key": {}
  },
  "organization_id": "organization_id",
  "product_id": "product_id",
  "requires_continuous_coverage": true,
  "scope": "PRODUCT",
  "status": "status",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "updated_at": "updated_at",
  "version": 0
}

json

application/json

List cost versions (with lifecycle filter)

GET

https://api.kontorion.eu/v1

/costs/{id}/versions

List cost versions (with lifecycle filter) › path Parameters

id

string · required

Cost UUID

List cost versions (with lifecycle filter) › query Parameters

status

string[] · style: form

Lifecycle status filter (repeatable)

List cost versions (with lifecycle filter) › Responses

200

object[]

archived_reason

string

created_at

string

created_by

string

effective_from

string

effective_to

string

id

string

ID is the *_versions.id UUID. Phase 2.D needs it so the FE stage-mode chip can wire selection→pin map without a separate number→ID lookup; older clients can ignore the field.

published_at

string

status

string

usage_count

integer

version

integer

object[]

Get a cost version snapshot

GET

https://api.kontorion.eu/v1

/costs/{id}/versions/{version}

Get a cost version snapshot › path Parameters

id

string · required

Cost UUID

version

integer · required

Version number

Get a cost version snapshot › Responses

200

object

cost_id

string

description

string

object

id

string

object

organization_id

string

published_at

string

published_by

string

object

version

integer

List costs (org-wide)

GET

https://api.kontorion.eu/v1

/products/{productId}/costs

Returns a paginated list of costs for the given product. Returns a paginated list of every active cost in the

List costs (org-wide) › path Parameters

productId

string · required

Product UUID

List costs (org-wide) › query Parameters

limit

integer

Page size

cursor

string

Pagination cursor

scope

string · enum

Filter by cost scope

Enum values:

ORG

PRODUCT

limit

integer

Page size

cursor

string

Pagination cursor

List costs (org-wide) › Responses

Paginated list with data and pagination envelope

object[]

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

GET/products/{productId}/costs

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

shell

Example Responses

{
  "key": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "archived_at": "archived_at",
      "created_at": "created_at",
      "description": "description",
      "expression": {
        "currency": "currency",
        "source": "source"
      },
      "head_version_id": "head_version_id",
      "id": "id",
      "key": "key",
      "metadata": {
        "key": {}
      },
      "organization_id": "organization_id",
      "product_id": "product_id",
      "requires_continuous_coverage": true,
      "scope": "PRODUCT",
      "status": "status",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "updated_at",
      "version": 0
    }
  ]
}

json

application/json

Create a cost

POST

https://api.kontorion.eu/v1

/products/{productId}/costs

Create a cost › path Parameters

productId

string · required

Product UUID (omit for org-scoped costs)

Create a cost › Request Body

object

description

string

object

key

string

object

product_id

string

object

Create a cost › Responses

Created

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

POST/products/{productId}/costs

curl --request POST \
  --url https://api.kontorion.eu/v1/products/:productId/costs \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "key": "key",
  "metadata": {
    "key": {}
  },
  "product_id": "product_id",
  "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": "product_id",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  }
}

json

Example Responses

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "archived_at": "archived_at",
  "created_at": "created_at",
  "description": "description",
  "expression": {
    "currency": "currency",
    "source": "source"
  },
  "head_version_id": "head_version_id",
  "id": "id",
  "key": "key",
  "metadata": {
    "key": {}
  },
  "organization_id": "organization_id",
  "product_id": "product_id",
  "requires_continuous_coverage": true,
  "scope": "PRODUCT",
  "status": "status",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "updated_at": "updated_at",
  "version": 0
}

json

application/json

Get a cost

GET

https://api.kontorion.eu/v1

/products/{productId}/costs/{costId}

Returns a single cost by UUID.

Get a cost › path Parameters

productId

string · required

Product UUID

costId

string · required

Cost UUID

Get a cost › Responses

Wrapped in data envelope

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

GET/products/{productId}/costs/{costId}

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

shell

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "archived_at",
    "created_at": "created_at",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "head_version_id": "head_version_id",
    "id": "id",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "organization_id",
    "product_id": "product_id",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "updated_at",
    "version": 0
  }
}

json

application/json

Update a cost

PUT

https://api.kontorion.eu/v1

/products/{productId}/costs/{costId}

Updates an existing cost by UUID.

Update a cost › path Parameters

productId

string · required

Product UUID

costId

string · required

Cost UUID

Update a cost › Request Body

object

description

string

effective_at

string

ADR-0006 edit-as-publish controls.

object

requires_continuous_coverage

boolean

Bucket-A: policy flag stored on the parent costs row. Edits propagate live; no cost_versions row is created. Pointer so we can distinguish "not provided" from "set to false".

save_as_draft

boolean

object

Update a cost › Responses

Wrapped in data envelope

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

PUT/products/{productId}/costs/{costId}

curl --request PUT \
  --url https://api.kontorion.eu/v1/products/:productId/costs/:costId \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "description": "description",
  "effective_at": "effective_at",
  "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": "effective_at",
  "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

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "archived_at",
    "created_at": "created_at",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "head_version_id": "head_version_id",
    "id": "id",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "organization_id",
    "product_id": "product_id",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "updated_at",
    "version": 0
  }
}

json

application/json

Archive a cost

DELETE

https://api.kontorion.eu/v1

/products/{productId}/costs/{costId}

Archives a cost by UUID (soft delete).

Archive a cost › path Parameters

productId

string · required

Product UUID

costId

string · required

Cost UUID

Archive a cost › Responses

No content

No data returned

Copy a cost

POST

https://api.kontorion.eu/v1

/products/{productId}/costs/{costId}/copy

Clones a cost (active or archived) into a new active cost. Prices that reference the source via formula expressions (cost.) keep their existing references to the original cost; the clone gets a new key.

Copy a cost › path Parameters

productId

string · required

Product UUID

costId

string · required

Source cost UUID

Copy a cost › Request Body

key

string

Copy a cost › Responses

Wrapped in data envelope

object

archived_at

string

created_at

string

description

string

object

head_version_id

string

id

string

key

string

object

organization_id

string

product_id

string

requires_continuous_coverage

boolean

scope

string · enum

Enum values:

PRODUCT

ORG

status

string

object

updated_at

string

version

integer

POST/products/{productId}/costs/{costId}/copy

curl --request POST \
  --url https://api.kontorion.eu/v1/products/:productId/costs/:costId/copy \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "key"
}'

shell

Example Request Body

{
  "key": "key"
}

json

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "archived_at": "archived_at",
    "created_at": "created_at",
    "description": "description",
    "expression": {
      "currency": "currency",
      "source": "source"
    },
    "head_version_id": "head_version_id",
    "id": "id",
    "key": "key",
    "metadata": {
      "key": {}
    },
    "organization_id": "organization_id",
    "product_id": "product_id",
    "requires_continuous_coverage": true,
    "scope": "PRODUCT",
    "status": "status",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "updated_at",
    "version": 0
  }
}

json

application/json

BulkArchive Scheduling/Costs