Products

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

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

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.kontorion.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"
          },
          "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"
        }
      ],
      "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",
      "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"
      ],
      "status": "draft",
      "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.kontorion.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

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.

name

string · maxLength: 255

Internal operator-facing product name.

Example: Premium Widget

pricing_model

string

Pricing model applied to this product; defaults to VOLUME when omitted.

Example: VOLUME

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.

quantity_source

string

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

Example: DECLARED

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"]

tax_category

string

Product tax category: DEFAULT, REDUCED, ZERO or EXEMPT; defaults to DEFAULT.

Example: DEFAULT

object

Locale-keyed overrides for name, description and public_description.

unit_label

string · maxLength: 64

Singular noun one billed unit is called; defaults to unit.

Example: seat

Create a product › Responses

Created

object · required

POST/products

curl --request POST \
  --url https://api.kontorion.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"
  ],
  "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"
  ],
  "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"
        },
        "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"
      }
    ],
    "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",
    "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"
    ],
    "status": "draft",
    "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.kontorion.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.kontorion.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"
        },
        "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"
      }
    ],
    "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",
    "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"
    ],
    "status": "draft",
    "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.kontorion.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.kontorion.eu/v1

/products/{id}

Merge-patch update: only supplied fields change. This is ALSO the publish surface (ADR-0006): send status="active" to publish the working draft, optionally with effective_at to schedule the flip (omitted or past = immediate) and save_as_draft=true to stage without publishing. 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.

effective_at

string · date-time

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

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

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

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.

save_as_draft

boolean

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

status

string · enum

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

Enum values:

draft

scheduled

active

archived

tax_category

string

New tax category (DEFAULT, REDUCED, 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.kontorion.eu/v1/products/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "effective_at": "2024-08-25T15:00:00Z",
  "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": "pricing_model",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "save_as_draft": true,
  "status": "draft",
  "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",
  "effective_at": "2024-08-25T15:00:00Z",
  "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": "pricing_model",
  "public_description": "public_description",
  "quantity_adjustable": true,
  "requires_product_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "save_as_draft": true,
  "status": "draft",
  "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"
        },
        "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"
      }
    ],
    "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",
    "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"
    ],
    "status": "draft",
    "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.kontorion.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.kontorion.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"
        },
        "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"
      }
    ],
    "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",
    "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"
    ],
    "status": "draft",
    "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.kontorion.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.kontorion.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

Discard the product's open working draft

DELETE

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

shell

Example Responses

{
  "data": [
    {
      "archived_reason": "archived_reason",
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "created_by",
      "effective_from": "2024-08-25T15:00:00Z",
      "effective_to": "2024-08-25T15:00:00Z",
      "id": "id",
      "published_at": "2024-08-25T15:00:00Z",
      "status": "draft",
      "usage_count": 0,
      "version": 0,
      "warnings": [
        {
          "field": "field",
          "type": "type"
        }
      ]
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Get a product version snapshot

GET

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

List product version referrers

GET

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

offset

string

Row offset (default 0)

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

Reservations Prices