Products

Endpointhttps://api.kontier.eu/v1

A product represents a billable item in your catalog - a feature, service, or resource that customers pay for. Products are the building blocks of plans and appear as line items on invoices.

Products can be recurring (charged every billing period), usage-based (metered and charged based on consumption), or one-time (charged once at purchase).

Key concepts:

Product type - recurring, usage, one_time, or seat - determines how charges are calculated
External ID - your internal SKU or product code for integration with other systems
Cost tracking - named COGS entries via costs[] (per-product or org-scoped) for margin analysis
Dependencies - requires_product_ids enforces that certain products must be purchased together

List products

GET

https://api.kontier.eu/v1

/products

Returns a paginated list of products. Supports the unified field.op=value filter grammar (see /docs/pagination) plus custom-field filters via the custom_fields.__ shape.

List products › query Parameters

created_at

string

Filter on created_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. created_at.gt=value; a bare created_at=value means eq.

external_id

string

Filter on external_id (string). Operators: eq, in — dot grammar, e.g. external_id.in=value; a bare external_id=value means eq. A bare comma-separated value is in-sugar: external_id=a,b means external_id.in=a,b.

invoiceable_standalone

string

Filter on invoiceable_standalone (boolean). Operators: eq — dot grammar, e.g. invoiceable_standalone.eq=value; a bare invoiceable_standalone=value means eq.

name

string

Filter on name (string). Operators: eq, in, contains — dot grammar, e.g. name.in=value; a bare name=value means eq. A bare comma-separated value is in-sugar: name=a,b means name.in=a,b.

pricing_model

string

Filter on pricing_model (enum). Operators: eq, in — dot grammar, e.g. pricing_model.in=value; a bare pricing_model=value means eq. A bare comma-separated value is in-sugar: pricing_model=a,b means pricing_model.in=a,b. Legal values: VOLUME, STAIRCASE, PACKAGE.

quantity_source

string

Filter on quantity_source (enum). Operators: eq, in — dot grammar, e.g. quantity_source.in=value; a bare quantity_source=value means eq. A bare comma-separated value is in-sugar: quantity_source=a,b means quantity_source.in=a,b. Legal values: DECLARED, METERED.

tax_category

string

Filter on tax_category (enum). Operators: eq, in — dot grammar, e.g. tax_category.in=value; a bare tax_category=value means eq. A bare comma-separated value is in-sugar: tax_category=a,b means tax_category.in=a,b. Legal values: DEFAULT, REDUCED, REDUCED_2, SUPER_REDUCED, PARKING, ZERO, EXEMPT.

updated_at

string

Filter on updated_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. updated_at.gt=value; a bare updated_at=value means eq.

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.

search

string

Case-insensitive substring match over name and external_id; relevance-ranked (exact > prefix > substring) unless an explicit sort is given

status

string

Filter by status (sugar for status.eq). Filterable fields (name, external_id, quantity_source, status, pricing_model, tax_category, invoiceable_standalone, created_at, updated_at) accept apifilter operator suffixes; custom_fields. filters are also supported

tag

string

Filter by tag name (repeatable, containment semantics)

counts

string

Comma-separated countable fields (status, quantity_source) to include per-value counts for

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.

sort

string

Ordering: created_at, status or quantity_source, each with an optional :asc/:desc suffix (default created_at:desc). quantity_source orders the whole archetype the Type badge reads - (quantity_source, quantity_adjustable, unit_label) - because ordering by quantity_source alone would interleave flat fees and per-seat rows. status and quantity_source order the stored codes, not their translated labels. Name is deliberately not sortable - product names are locale-translated after the query, so SQL would order the English base value. An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page. Sorting suppresses relevance ranking when search is also given.

List products › 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 products › Responses

array | null · required

object · required

GET/products

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

shell

Example Responses

{
  "data": [
    {
      "active_price_count": 0,
      "allowed_pricing_models": [
        "PACKAGE"
      ],
      "cost_summary": [
        {
          "cost_count": 0,
          "currency": "currency",
          "total_amount": "49.5"
        }
      ],
      "costs": [
        {
          "amount": {
            "currency": "EUR",
            "value": "49.5"
          },
          "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,
          "retired_at": "2024-08-25T15:00:00Z",
          "scope": "PRODUCT",
          "status": "status",
          "translations": {
            "key": {
              "description": "description",
              "name": "name",
              "public_description": "public_description"
            }
          },
          "updated_at": "2024-08-25T15:00:00Z"
        }
      ],
      "created_at": "2024-08-25T15:00:00Z",
      "custom_fields": {
        "key": {}
      },
      "deleted_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "external_id": "external_id",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoiceable_standalone": true,
      "key_set_excluded_keys": [
        "string"
      ],
      "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "lifecycle": "draft",
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "pricing_model": "PACKAGE",
      "public_description": "public_description",
      "quantity_adjustable": true,
      "quantity_source": "DECLARED",
      "requires_product_ids": [
        "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"
        }
      ],
      "status": "draft",
      "supply_nature": "supply_nature",
      "tags": [
        {
          "archived_at": "2024-08-25T15:00:00Z",
          "color": "color",
          "created_at": "2024-08-25T15:00:00Z",
          "deleted_at": "2024-08-25T15:00:00Z",
          "description": "description",
          "entity_type": "CUSTOMER",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "name": "name",
          "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "updated_at": "2024-08-25T15:00:00Z",
          "usage_count": 0
        }
      ],
      "tax_category": "DEFAULT",
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "unit_label": "unit_label",
      "updated_at": "2024-08-25T15:00:00Z",
      "version": 0
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a product

POST

https://api.kontier.eu/v1

/products

Creates a new product in draft status.

Create a product › 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 product › Request Body

name

string · minLength: 1 · maxLength: 255 · required

Internal operator-facing product name.

Example: Premium Widget

pricing_model

string · enum · required

Pricing model applied to this product: VOLUME, STAIRCASE or PACKAGE. Required.

Enum values:

VOLUME

STAIRCASE

PACKAGE

Example: VOLUME

quantity_source

string · enum · required

Where the billed quantity comes from: DECLARED (set on the subscription item) or METERED (from the meter evaluator). Required.

Enum values:

DECLARED

METERED

Example: DECLARED

unit_label

string · minLength: 1 · maxLength: 64 · required

Singular noun one billed unit is called (e.g. seat, GB). Required.

Example: seat

object

Org-defined custom field values for this product.

description

string · maxLength: 2000

Internal operator-facing description; not shown to buyers.

external_id

string · maxLength: 255

Caller-supplied external identifier for reconciliation with an upstream system.

Example: sku-premium-widget

invoiceable_standalone

boolean

Whether the product may appear in the manual-invoice picker; absent defaults to true, explicit false marks it subscription-only.

key_set_excluded_keys

array | null · maxItems: 500

Keys subtracted from the linked key set's active entries (subtract-only).

key_set_id

string · uuid

Opts the product into keyed pricing by linking it to an org-global key set.

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

object

Free-form operator key/value metadata.

public_description

string · maxLength: 2000

Buyer-facing description shown in checkout and the customer portal.

quantity_adjustable

boolean

When true the buyer picks the quantity (seats/licenses); defaults to false (flat charge) and is rejected on METERED products.

requires_product_ids

array | null · maxItems: 500

Products that must also be present for this product to be sold (dependency set).

Example: ["0f8fad5b-d9cb-469f-a165-70867728950e"]

supply_nature

string · enum

What this product is for place-of-supply purposes. Omit to leave it undeclared, which is treated as SERVICES.

Enum values:

GOODS

SERVICES

DIGITAL_SERVICES

Example: SERVICES

tax_category

string · enum

Product tax category: which statutory tier the product is billed at. DEFAULT is the country's standard rate; ZERO and EXEMPT are decided by what the supply is and are not tiers. Defaults to DEFAULT.

Enum values:

DEFAULT

REDUCED

REDUCED_2

SUPER_REDUCED

PARKING

ZERO

EXEMPT

Example: DEFAULT

object

Locale-keyed overrides for name, description and public_description.

Create a product › Responses

Created

object · required

POST/products

curl --request POST \
  --url https://api.kontier.eu/v1/products \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "external_id": "sku-premium-widget",
  "invoiceable_standalone": true,
  "key_set_excluded_keys": [
    "string"
  ],
  "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "metadata": {
    "key": {}
  },
  "name": "Premium Widget",
  "pricing_model": "VOLUME",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "quantity_source": "DECLARED",
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "supply_nature": "SERVICES",
  "tax_category": "DEFAULT",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "unit_label": "seat"
}
'

shell

Example Request Body

{
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "external_id": "sku-premium-widget",
  "invoiceable_standalone": true,
  "key_set_excluded_keys": [
    "string"
  ],
  "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "metadata": {
    "key": {}
  },
  "name": "Premium Widget",
  "pricing_model": "VOLUME",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "quantity_source": "DECLARED",
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "supply_nature": "SERVICES",
  "tax_category": "DEFAULT",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "unit_label": "seat"
}

json

Example Responses

{
  "data": {
    "active_price_count": 0,
    "allowed_pricing_models": [
      "PACKAGE"
    ],
    "cost_summary": [
      {
        "cost_count": 0,
        "currency": "currency",
        "total_amount": "49.5"
      }
    ],
    "costs": [
      {
        "amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "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,
        "retired_at": "2024-08-25T15:00:00Z",
        "scope": "PRODUCT",
        "status": "status",
        "translations": {
          "key": {
            "description": "description",
            "name": "name",
            "public_description": "public_description"
          }
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "custom_fields": {
      "key": {}
    },
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "external_id": "external_id",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoiceable_standalone": true,
    "key_set_excluded_keys": [
      "string"
    ],
    "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle": "draft",
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "pricing_model": "PACKAGE",
    "public_description": "public_description",
    "quantity_adjustable": true,
    "quantity_source": "DECLARED",
    "requires_product_ids": [
      "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"
      }
    ],
    "status": "draft",
    "supply_nature": "supply_nature",
    "tags": [
      {
        "archived_at": "2024-08-25T15:00:00Z",
        "color": "color",
        "created_at": "2024-08-25T15:00:00Z",
        "deleted_at": "2024-08-25T15:00:00Z",
        "description": "description",
        "entity_type": "CUSTOMER",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "updated_at": "2024-08-25T15:00:00Z",
        "usage_count": 0
      }
    ],
    "tax_category": "DEFAULT",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "unit_label": "unit_label",
    "updated_at": "2024-08-25T15:00:00Z",
    "version": 0
  }
}

json

application/json

Get a product

GET

https://api.kontier.eu/v1

/products/{id}

Returns a single product enriched with its active-price count; translatable fields are localized to the caller's locale.

Get a product › path Parameters

id

string · uuid · required

Product UUID

Get a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a product › Responses

object · required

GET/products/{id}

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

shell

Example Responses

{
  "data": {
    "active_price_count": 0,
    "allowed_pricing_models": [
      "PACKAGE"
    ],
    "cost_summary": [
      {
        "cost_count": 0,
        "currency": "currency",
        "total_amount": "49.5"
      }
    ],
    "costs": [
      {
        "amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "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,
        "retired_at": "2024-08-25T15:00:00Z",
        "scope": "PRODUCT",
        "status": "status",
        "translations": {
          "key": {
            "description": "description",
            "name": "name",
            "public_description": "public_description"
          }
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "custom_fields": {
      "key": {}
    },
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "external_id": "external_id",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoiceable_standalone": true,
    "key_set_excluded_keys": [
      "string"
    ],
    "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle": "draft",
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "pricing_model": "PACKAGE",
    "public_description": "public_description",
    "quantity_adjustable": true,
    "quantity_source": "DECLARED",
    "requires_product_ids": [
      "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"
      }
    ],
    "status": "draft",
    "supply_nature": "supply_nature",
    "tags": [
      {
        "archived_at": "2024-08-25T15:00:00Z",
        "color": "color",
        "created_at": "2024-08-25T15:00:00Z",
        "deleted_at": "2024-08-25T15:00:00Z",
        "description": "description",
        "entity_type": "CUSTOMER",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "updated_at": "2024-08-25T15:00:00Z",
        "usage_count": 0
      }
    ],
    "tax_category": "DEFAULT",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "unit_label": "unit_label",
    "updated_at": "2024-08-25T15:00:00Z",
    "version": 0
  }
}

json

application/json

Delete a product

DELETE

https://api.kontier.eu/v1

/products/{id}

Soft-deletes a product by UUID.

Delete a product › path Parameters

id

string · uuid · required

Product UUID

Delete a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a product › Responses

No Content

No data returned

Update a product

PATCH

https://api.kontier.eu/v1

/products/{id}

Merge-patch update: only supplied fields change, and none of them publish. Display fields (name, description, metadata, external_id, …) land live on the product immediately; every billing change is a child — a price, a cost, a meter binding — and is buffered into the product's working draft, which you can read with GET /v1/products/{id}/draft and discard with DELETE. Taking the draft live, now or on a date, is POST /v1/changes with operation catalog.publish_version and subject_kind=product: status="active" here is refused, and there is no effective_at or save_as_draft. status can still archive the product, which is terminal. expected_version is the optimistic-concurrency token: when supplied and stale, the update returns 409.

Update a product › path Parameters

id

string · uuid · required

Product UUID

Update a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a product › Request Body

object

Org-defined custom field values for this product.

description

string · maxLength: 2000

New internal description; null leaves it unchanged.

expected_version

integer · int64

Optimistic-concurrency token: send the version you last read and a stale value answers 409 CONFLICT. Omitted: the update applies unconditionally (last write wins).

external_id

string · maxLength: 255

New external identifier; null leaves it unchanged.

invoiceable_standalone

boolean

Flips the manual-invoice picker eligibility; null leaves it unchanged.

key_set_excluded_keys

array | null · maxItems: 500

Replacement excluded-keys list; null leaves it unchanged, non-null replaces the list.

key_set_id

string · uuid

Links or clears the product's key set; changing it once the product has keyed prices or items is rejected.

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

object

Free-form operator key/value metadata.

name

string · maxLength: 255

New internal product name; null leaves it unchanged.

pricing_model

string · enum

New pricing model (VOLUME, STAIRCASE, PACKAGE); null leaves it unchanged.

Enum values:

PACKAGE

STAIRCASE

VOLUME

public_description

string · maxLength: 2000

New buyer-facing description; null leaves it unchanged.

quantity_adjustable

boolean

Flips whether the buyer picks the quantity; null leaves it unchanged, and setting true on a METERED product is rejected.

requires_product_ids

array | null · maxItems: 500

Replacement product-dependency set for this product.

status

string · enum

New catalog lifecycle status (draft, scheduled, active, archived); null leaves it unchanged.

Enum values:

draft

scheduled

active

archived

supply_nature

string

New supply nature (GOODS, SERVICES, DIGITAL_SERVICES); null leaves it unchanged, empty string clears the declaration.

tax_category

string

New tax category (DEFAULT, REDUCED, REDUCED_2, SUPER_REDUCED, PARKING, ZERO, EXEMPT); null leaves it unchanged.

object

Locale-keyed overrides for name, description and public_description.

unit_label

string · maxLength: 64

New singular unit label; null leaves it unchanged. quantity_source itself is immutable post-create.

Update a product › Responses

object · required

PATCH/products/{id}

curl --request PATCH \
  --url https://api.kontier.eu/v1/products/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "expected_version": 0,
  "external_id": "external_id",
  "invoiceable_standalone": true,
  "key_set_excluded_keys": [
    "string"
  ],
  "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "pricing_model": "PACKAGE",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "status": "draft",
  "supply_nature": "supply_nature",
  "tax_category": "tax_category",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "unit_label": "unit_label"
}
'

shell

Example Request Body

{
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "expected_version": 0,
  "external_id": "external_id",
  "invoiceable_standalone": true,
  "key_set_excluded_keys": [
    "string"
  ],
  "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "pricing_model": "PACKAGE",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "status": "draft",
  "supply_nature": "supply_nature",
  "tax_category": "tax_category",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "unit_label": "unit_label"
}

json

Example Responses

{
  "data": {
    "active_price_count": 0,
    "allowed_pricing_models": [
      "PACKAGE"
    ],
    "cost_summary": [
      {
        "cost_count": 0,
        "currency": "currency",
        "total_amount": "49.5"
      }
    ],
    "costs": [
      {
        "amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "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,
        "retired_at": "2024-08-25T15:00:00Z",
        "scope": "PRODUCT",
        "status": "status",
        "translations": {
          "key": {
            "description": "description",
            "name": "name",
            "public_description": "public_description"
          }
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "custom_fields": {
      "key": {}
    },
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "external_id": "external_id",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoiceable_standalone": true,
    "key_set_excluded_keys": [
      "string"
    ],
    "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle": "draft",
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "pricing_model": "PACKAGE",
    "public_description": "public_description",
    "quantity_adjustable": true,
    "quantity_source": "DECLARED",
    "requires_product_ids": [
      "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"
      }
    ],
    "status": "draft",
    "supply_nature": "supply_nature",
    "tags": [
      {
        "archived_at": "2024-08-25T15:00:00Z",
        "color": "color",
        "created_at": "2024-08-25T15:00:00Z",
        "deleted_at": "2024-08-25T15:00:00Z",
        "description": "description",
        "entity_type": "CUSTOMER",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "updated_at": "2024-08-25T15:00:00Z",
        "usage_count": 0
      }
    ],
    "tax_category": "DEFAULT",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "unit_label": "unit_label",
    "updated_at": "2024-08-25T15:00:00Z",
    "version": 0
  }
}

json

application/json

Duplicate a product

POST

https://api.kontier.eu/v1

/products/{id}/copy

Creates a new product whose attributes are copied from the source. Prices, costs and meter bindings on the source are NOT copied; only the product definition.

Duplicate a product › path Parameters

id

string · uuid · required

Source product UUID

Duplicate a product › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Duplicate a product › Request Body

external_id

string · maxLength: 255

External identifier for the new draft copy.

name

string · maxLength: 255

Name for the new draft copy; defaults to a derived copy name when omitted.

Duplicate a product › Responses

Created

object · required

POST/products/{id}/copy

curl --request POST \
  --url https://api.kontier.eu/v1/products/:id/copy \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "external_id": "external_id",
  "name": "name"
}
'

shell

Example Request Body

{
  "external_id": "external_id",
  "name": "name"
}

json

Example Responses

{
  "data": {
    "active_price_count": 0,
    "allowed_pricing_models": [
      "PACKAGE"
    ],
    "cost_summary": [
      {
        "cost_count": 0,
        "currency": "currency",
        "total_amount": "49.5"
      }
    ],
    "costs": [
      {
        "amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "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,
        "retired_at": "2024-08-25T15:00:00Z",
        "scope": "PRODUCT",
        "status": "status",
        "translations": {
          "key": {
            "description": "description",
            "name": "name",
            "public_description": "public_description"
          }
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "custom_fields": {
      "key": {}
    },
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "external_id": "external_id",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoiceable_standalone": true,
    "key_set_excluded_keys": [
      "string"
    ],
    "key_set_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "lifecycle": "draft",
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "pricing_model": "PACKAGE",
    "public_description": "public_description",
    "quantity_adjustable": true,
    "quantity_source": "DECLARED",
    "requires_product_ids": [
      "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"
      }
    ],
    "status": "draft",
    "supply_nature": "supply_nature",
    "tags": [
      {
        "archived_at": "2024-08-25T15:00:00Z",
        "color": "color",
        "created_at": "2024-08-25T15:00:00Z",
        "deleted_at": "2024-08-25T15:00:00Z",
        "description": "description",
        "entity_type": "CUSTOMER",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "updated_at": "2024-08-25T15:00:00Z",
        "usage_count": 0
      }
    ],
    "tax_category": "DEFAULT",
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "unit_label": "unit_label",
    "updated_at": "2024-08-25T15:00:00Z",
    "version": 0
  }
}

json

application/json

List plans that use this product

GET

https://api.kontier.eu/v1

/products/{id}/dependent-plans

Every plan that includes this product, with the pinned product version, the live head, the membership track mode, and a stale flag (pinned != head).

List plans that use this product › path Parameters

id

string · uuid · required

Product UUID

List plans that use this product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List plans that use this product › Responses

array | null · required

object · required

Get the product's open working draft

GET

https://api.kontier.eu/v1

/products/{id}/draft

The open working-draft metadata (draft version id, number, created_at, changed-child counts vs the head). 404 when the product has no open draft.

Get the product's open working draft › path Parameters

id

string · uuid · required

Product UUID

Get the product's open working draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the product's open working draft › Responses

object · required

GET/products/{id}/draft

curl --request GET \
  --url https://api.kontier.eu/v1/products/:id/draft

shell

Example Responses

{
  "data": {
    "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "changes": {
      "bindings": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "costs": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "prices": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "total": 0
    },
    "created_at": "2024-08-25T15:00:00Z",
    "draft_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "release_name": "release_name",
    "release_note": "release_note",
    "summary": {
      "kinds": [
        {
          "count": 0,
          "kind": "kind"
        }
      ],
      "total": 0
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "updated_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "version": 0
  }
}

json

application/json

Open the product's working draft on a chosen base

POST

https://api.kontier.eu/v1

/products/{id}/draft

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

Open the product's working draft on a chosen base › path Parameters

id

string · uuid · required

Product UUID

Open the product's working draft on a chosen base › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Open the product's working draft on a chosen base › Request Body

base_version_id

string · uuid

The version the working draft is authored on top of — the live head, or one of the entity's scheduled versions. Omit for the head. Rebasing an existing draft keeps its edits and re-materialises them over the new base.

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

Open the product's working draft on a chosen base › Responses

object · required

POST/products/{id}/draft

curl --request POST \
  --url https://api.kontier.eu/v1/products/:id/draft \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "base_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "changes": {
      "bindings": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "costs": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "prices": {
        "added": 0,
        "changed": 0,
        "removed": 0
      },
      "total": 0
    },
    "created_at": "2024-08-25T15:00:00Z",
    "draft_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "release_name": "release_name",
    "release_note": "release_note",
    "summary": {
      "kinds": [
        {
          "count": 0,
          "kind": "kind"
        }
      ],
      "total": 0
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "updated_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "version": 0
  }
}

json

application/json

Discard the product's open working draft

DELETE

https://api.kontier.eu/v1

/products/{id}/draft

Deletes the open working-draft version row; its revision rows cascade. 404 when no draft is open.

Discard the product's open working draft › path Parameters

id

string · uuid · required

Product UUID

Discard the product's open working draft › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Discard the product's open working draft › Responses

No Content

No data returned

Preview the impact of publishing a product

GET

https://api.kontier.eu/v1

/products/{id}/publish-impact

Read-only dry-run: the active plans that auto-follow this product ('latest' membership) and would be republished, plus the number of subscriptions that would migrate.

Preview the impact of publishing a product › path Parameters

id

string · uuid · required

Product UUID

Preview the impact of publishing a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Preview the impact of publishing a product › Responses

object · required

List product versions (with lifecycle filter)

GET

https://api.kontier.eu/v1

/products/{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 product versions (with lifecycle filter) › path Parameters

id

string · uuid · required

Entity UUID

List product 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 product versions (with lifecycle filter) › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List product versions (with lifecycle filter) › Responses

array | null · required

object · required

GET/products/{id}/versions

curl --request GET \
  --url https://api.kontier.eu/v1/products/: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 product version snapshot

GET

https://api.kontier.eu/v1

/products/{id}/versions/{version}

Returns the full snapshot row from product_versions, including the Phase 2.D child version pin maps.

Get a product version snapshot › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number

Get a product version snapshot › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a product version snapshot › Responses

object · required

GET/products/{id}/versions/{version}

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

shell

Example Responses

{
  "data": {
    "description": "description",
    "effective_from": "2024-08-25T15:00:00Z",
    "effective_to": "2024-08-25T15:00:00Z",
    "external_id": "external_id",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "metadata": "metadata",
    "name": "name",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_status": "product_status",
    "published_at": "2024-08-25T15:00:00Z",
    "published_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "release_strategy": "release_strategy",
    "status": "status",
    "version": 0
  }
}

json

application/json

Name or annotate a product version

PATCH

https://api.kontier.eu/v1

/products/{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 product version › path Parameters

id

string · uuid · required

Entity UUID

version

integer · int64 · min: 1 · required

The version number

Name or annotate a product version › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Name or annotate a product 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 product 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/products/{id}/versions/{version}

curl --request PATCH \
  --url https://api.kontier.eu/v1/products/: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 product version

GET

https://api.kontier.eu/v1

/products/{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 product version › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

Forecast the impact of superseding this product version › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Forecast the impact of superseding this product version › Responses

object · required

GET/products/{id}/versions/{version}/publish-impact

curl --request GET \
  --url https://api.kontier.eu/v1/products/: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 product version referrers

GET

https://api.kontier.eu/v1

/products/{id}/versions/{version}/referrers

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

List product version referrers › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

List product 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 product version referrers › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List product version referrers › Responses

array | null · required

object · required

GET/products/{id}/versions/{version}/referrers

curl --request GET \
  --url https://api.kontier.eu/v1/products/: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 product version usage summary

GET

https://api.kontier.eu/v1

/products/{id}/versions/{version}/usage

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

Get product version usage summary › path Parameters

id

string · uuid · required

Entity UUID

version

string · required

Version number (positive integer)

Get product version usage summary › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get product version usage summary › Responses

object · required

Transactions Prices