Subscriptions

Endpointhttps://api.kontier.eu/v1

A subscription is a contract between your business and a customer - it defines which plan they're on, what billing period applies, and how charges are generated over time.

Subscriptions progress through a defined lifecycle: pending → trialing → active → past_due → canceled or expired. Each transition can trigger invoicing, proration, or dunning actions.

Key concepts:

Plan - the pricing template attached to this subscription
Billing period - month, quarter, or year - determines invoice frequency
Trial - an optional free period before charges begin
Auto-renew - whether the subscription renews automatically at period end
Billing anchor day - the day of month that billing cycles align to (e.g., the 1st or 15th)
Proration - when a subscription changes mid-cycle, charges are adjusted proportionally
Items - the specific products and quantities included in this subscription

List subscriptions

GET

https://api.kontier.eu/v1

/subscriptions

Cursor-paginated list with optional column filters (status, customer_id, plan_id, …), custom_fields. filters, and the versioning drift extensions (?include=drift, ?versions_behind*, ?sort=versions_behind_*).

List subscriptions › query Parameters

auto_renew

string

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

billing_interval_unit

string

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

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.

currency

string

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

current_period_end

string

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

current_period_start

string

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

customer_id

string

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

deviates_from_plan

string

Filter on deviates_from_plan (boolean). Derived boolean predicate: only deviates_from_plan=true|false (eq).

plan_id

string

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

plan_version

string

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

started_at

string

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

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 customer name/email, plan name and the subscription's human reference (e.g. SUB-000123)

status

string

Filter by status. Filterable fields (status, customer_id, plan_id, plan_version, billing_interval_unit, currency, auto_renew, started_at, current_period_start, current_period_end, created_at, updated_at, deviates_from_plan) 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, billing_cycle_anchor_unit) to include per-value counts for

include

string

Comma/repeat includes. 'drift' attaches {versions_behind, latest_version} per row

versions_behind_min

string

Keep only subscriptions at least N versions behind (mutually exclusive with versions_behind)

versions_behind

string

Keep only subscriptions exactly N versions behind

sort

string

Ordering: created_at with an optional :asc/:desc suffix (default created_at:desc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page. The legacy values versions_behind_desc | versions_behind_asc are NOT a keyset ordering: they leave the created_at walk in place and reorder only the rows of the page already fetched, by the drift figure computed in Go.

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

array | null · required

object · required

GET/subscriptions

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

shell

Example Responses

{
  "data": [
    {
      "active_promotions": [
        {
          "discount_value": "discount_value",
          "effect_type": "effect_type",
          "expires_at": "2024-08-25T15:00:00Z",
          "name": "name",
          "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
        }
      ],
      "allowed_transitions": [
        "DRAFT"
      ],
      "arr": {
        "currency": "EUR",
        "value": "49.5"
      },
      "auto_renew": true,
      "billing_anchor_day": 0,
      "billing_interval_count": 0,
      "billing_interval_unit": "month",
      "billing_timing": "in_advance",
      "cancellation_reason": "USER_REQUEST",
      "cancelled_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "currency": "currency",
      "current_period_end": "2026-07-01",
      "current_period_start": "2026-07-01",
      "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "custom_fields": {
        "key": {}
      },
      "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "deleted_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "deviation": {
        "count": 0,
        "deviates": true,
        "kinds": [
          "string"
        ]
      },
      "display_name": "display_name",
      "drift": {
        "latest_version": 0,
        "versions_behind": 0
      },
      "ending": {
        "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "at": "2024-08-25T15:00:00Z",
        "kind": "RUNS_UNTIL_CANCELLED"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "items": [
        {
          "charge_span_count": 0,
          "charge_span_unit": "month",
          "created_at": "2024-08-25T15:00:00Z",
          "display_name": "display_name",
          "effective_from": "2024-08-25T15:00:00Z",
          "effective_to": "2024-08-25T15:00:00Z",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "override_applied": true,
          "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "override_source": "override_source",
          "price_key": "price_key",
          "pricing_model": "PACKAGE",
          "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "product_name": "product_name",
          "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "quantity": 0,
          "quantity_adjustable": true,
          "quantity_source": "DECLARED",
          "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "total_price": {
            "currency": "EUR",
            "value": "49.5"
          },
          "unit_label": "unit_label",
          "unit_price": {
            "currency": "EUR",
            "value": "49.5"
          },
          "updated_at": "2024-08-25T15:00:00Z"
        }
      ],
      "metadata": {
        "key": {}
      },
      "mrr": {
        "currency": "EUR",
        "value": "49.5"
      },
      "name": "name",
      "next_billing_date": "2024-08-25T15:00:00Z",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "payment_terms_days": 0,
      "pending_checkout_session_id": "pending_checkout_session_id",
      "phases": [
        {
          "auto_transition": true,
          "completed_at": "2024-08-25T15:00:00Z",
          "created_at": "2024-08-25T15:00:00Z",
          "dunning_stage": "WARNED",
          "dunning_stage_at": "2024-08-25T15:00:00Z",
          "duration_unit": "day",
          "duration_value": 0,
          "end_at": "2024-08-25T15:00:00Z",
          "end_kind": "manual",
          "ends_at": "2024-08-25T15:00:00Z",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "phase_kind": "setup",
          "phase_order": 0,
          "started_at": "2024-08-25T15:00:00Z",
          "status": "PENDING",
          "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
        }
      ],
      "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "plan_version": 0,
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_version": 0,
      "public_description": "public_description",
      "reference": "reference",
      "settings": {
        "default_proration_mode": "pro_rata",
        "line_grouping": "line_grouping",
        "price_resolution_policy": "price_resolution_policy"
      },
      "start_at": "2024-08-25T15:00:00Z",
      "start_trigger": "immediate",
      "started_at": "2024-08-25T15:00:00Z",
      "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
        }
      ],
      "translations": {
        "key": {
          "description": "description",
          "name": "name",
          "public_description": "public_description"
        }
      },
      "updated_at": "2024-08-25T15:00:00Z",
      "version_change_strategy": "immediate_prorate",
      "version_track_mode": "pinned"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a subscription

POST

https://api.kontier.eu/v1

/subscriptions

Creates a subscription for a customer. Items, billing interval and currency derive from the request.

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

customer_id

string · uuid · required

Customer the subscription bills; required.

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

auto_renew

boolean

Whether the subscription renews automatically at period end; false lets it expire when the current period closes.

billing_anchor_day

integer · int64

Day of the month (1-28) each billing period starts on; derived from the activation date when omitted.

billing_interval_count

integer · int64

Number of interval units per billing cycle; defaults to 1.

billing_interval_unit

string · enum

Unit of the billing cycle length: week, month or year; defaults to month. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.

Enum values:

month

week

year

billing_timing

string · enum

When invoices fire relative to the period: in_advance (at period start) or in_arrears (at period end); defaults to in_arrears.

Enum values:

in_advance

in_arrears

currency

string

ISO 4217 currency this subscription bills in, for its whole life - it is the contract and cannot be changed afterwards. Defaults to the customer's preferred_currency, else the currency of the plan version's first price, else EUR. The organization default is NOT consulted here.

object

Values for the org's configured custom fields.

description

string · maxLength: 2000

Internal operator-facing description; not shown to buyers.

free_trial_days

integer · int64 · min: 0 · max: 3650

Length of the free trial in days before billing starts; 0 or omitted means billing starts immediately.

array | null · maxItems: 500

Products, quantities and prices billed by this subscription; defaults from the plan-version snapshot for plan-based subs when omitted.

object

Arbitrary caller-supplied key/value pairs.

name

string · maxLength: 200

Internal operator-facing subscription name.

payment_terms_days

integer · int64

Net payment window in days for this subscription's invoices (0-365); null inherits the org default.

pending_checkout_session_id

string · maxLength: 255

Provider checkout session to bind an on_checkout_complete DRAFT to; set by the public-checkout finalizer only.

plan_id

string · uuid

Plan to base the subscription on; mutually exclusive with product_id (plan-or-product XOR).

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

product_id

string · uuid

Product to bill directly; mutually exclusive with plan_id (plan-or-product XOR).

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

product_version

integer · int64

Product version to pin; null follows the product head version.

public_description

string · maxLength: 2000

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

object

Per-subscription billing setting overrides; unset keys inherit from customer, then org, then default.

start_at

string · date-time

Activation instant; required when start_trigger is start_date, rejected otherwise.

start_trigger

string · enum

What activates the DRAFT subscription: immediate, on_checkout_complete, manual or start_date; defaults to immediate.

Enum values:

immediate

on_checkout_complete

manual

start_date

object

Locale-keyed overrides for name, description and public_description.

version_change_strategy

string · enum

Money policy for auto-upgrades: immediate_prorate, next_period or at_phase_change; required when version_track_mode is latest.

Enum values:

immediate_prorate

next_period

at_phase_change

version_track_mode

string · enum

How the subscription follows plan/product versions: pinned or latest. Defaults to LATEST paired with immediate_prorate, so publishing a new plan version DOES migrate this subscription and can charge proration for it. Send pinned explicitly to opt out.

Enum values:

pinned

latest

Create a subscription › Responses

Created

object · required

POST/subscriptions

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "auto_renew": true,
  "billing_anchor_day": 0,
  "billing_interval_count": 0,
  "billing_interval_unit": "month",
  "billing_timing": "in_advance",
  "currency": "currency",
  "custom_fields": {
    "key": {}
  },
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "description": "description",
  "free_trial_days": 0,
  "items": [
    {
      "charge_span_count": 0,
      "charge_span_unit": "month",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": 5
    }
  ],
  "metadata": {
    "key": {}
  },
  "name": "name",
  "payment_terms_days": 0,
  "pending_checkout_session_id": "pending_checkout_session_id",
  "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "product_version": 0,
  "public_description": "public_description",
  "settings": {
    "default_proration_mode": "pro_rata",
    "line_grouping": "line_grouping",
    "price_resolution_policy": "price_resolution_policy"
  },
  "start_at": "2024-08-25T15:00:00Z",
  "start_trigger": "immediate",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "version_change_strategy": "immediate_prorate",
  "version_track_mode": "pinned"
}
'

shell

Example Request Body

{
  "auto_renew": true,
  "billing_anchor_day": 0,
  "billing_interval_count": 0,
  "billing_interval_unit": "month",
  "billing_timing": "in_advance",
  "currency": "currency",
  "custom_fields": {
    "key": {}
  },
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "description": "description",
  "free_trial_days": 0,
  "items": [
    {
      "charge_span_count": 0,
      "charge_span_unit": "month",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": 5
    }
  ],
  "metadata": {
    "key": {}
  },
  "name": "name",
  "payment_terms_days": 0,
  "pending_checkout_session_id": "pending_checkout_session_id",
  "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "product_version": 0,
  "public_description": "public_description",
  "settings": {
    "default_proration_mode": "pro_rata",
    "line_grouping": "line_grouping",
    "price_resolution_policy": "price_resolution_policy"
  },
  "start_at": "2024-08-25T15:00:00Z",
  "start_trigger": "immediate",
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "version_change_strategy": "immediate_prorate",
  "version_track_mode": "pinned"
}

json

Example Responses

{
  "data": {
    "active_promotions": [
      {
        "discount_value": "discount_value",
        "effect_type": "effect_type",
        "expires_at": "2024-08-25T15:00:00Z",
        "name": "name",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "allowed_transitions": [
      "DRAFT"
    ],
    "arr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_renew": true,
    "billing_anchor_day": 0,
    "billing_interval_count": 0,
    "billing_interval_unit": "month",
    "billing_timing": "in_advance",
    "cancellation_reason": "USER_REQUEST",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "current_period_end": "2026-07-01",
    "current_period_start": "2026-07-01",
    "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "custom_fields": {
      "key": {}
    },
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "deviation": {
      "count": 0,
      "deviates": true,
      "kinds": [
        "string"
      ]
    },
    "display_name": "display_name",
    "drift": {
      "latest_version": 0,
      "versions_behind": 0
    },
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "items": [
      {
        "charge_span_count": 0,
        "charge_span_unit": "month",
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_applied": true,
        "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_source": "override_source",
        "price_key": "price_key",
        "pricing_model": "PACKAGE",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "quantity": 0,
        "quantity_adjustable": true,
        "quantity_source": "DECLARED",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "total_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_label": "unit_label",
        "unit_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "metadata": {
      "key": {}
    },
    "mrr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "name": "name",
    "next_billing_date": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "payment_terms_days": 0,
    "pending_checkout_session_id": "pending_checkout_session_id",
    "phases": [
      {
        "auto_transition": true,
        "completed_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "dunning_stage": "WARNED",
        "dunning_stage_at": "2024-08-25T15:00:00Z",
        "duration_unit": "day",
        "duration_value": 0,
        "end_at": "2024-08-25T15:00:00Z",
        "end_kind": "manual",
        "ends_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "phase_kind": "setup",
        "phase_order": 0,
        "started_at": "2024-08-25T15:00:00Z",
        "status": "PENDING",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_version": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_version": 0,
    "public_description": "public_description",
    "reference": "reference",
    "settings": {
      "default_proration_mode": "pro_rata",
      "line_grouping": "line_grouping",
      "price_resolution_policy": "price_resolution_policy"
    },
    "start_at": "2024-08-25T15:00:00Z",
    "start_trigger": "immediate",
    "started_at": "2024-08-25T15:00:00Z",
    "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
      }
    ],
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "version_change_strategy": "immediate_prorate",
    "version_track_mode": "pinned"
  }
}

json

application/json

Bulk-upgrade a set of subscriptions to a target version

POST

https://api.kontier.eu/v1

/subscriptions/bulk-upgrade

Fans out per-sub change-version calls for each entry in subscription_ids. Honors version_track_mode='pinned' by skipping pinned subs (set force=true to override). Returns the success+skipped breakdown.

Bulk-upgrade a set of subscriptions to a target version › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Bulk-upgrade a set of subscriptions to a target version › Request Body

strategy

string · enum · required

Money policy for each upgrade: immediate_prorate, next_period or at_phase_change.

Enum values:

immediate_prorate

next_period

at_phase_change

subscription_ids

array | null · maxItems: 500 · required

Subscriptions to upgrade; at least one, at most 500.

force

boolean

When true, upgrade even subscriptions pinned to their current version.

scheduled_at

string · date-time

Reserved for future scheduling; rejected with a validation error when set (per-sub scheduling parity is a pending followup).

target_plan_version

integer · int64

Plan version to move plan-based subscriptions to; null leaves plan-based subs untouched.

target_product_version

integer · int64

Product version to move product-based subscriptions to; null leaves product-based subs untouched.

Bulk-upgrade a set of subscriptions to a target version › Responses

object · required

POST/subscriptions/bulk-upgrade

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/bulk-upgrade \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "force": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "strategy": "immediate_prorate",
  "subscription_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "target_plan_version": 0,
  "target_product_version": 0
}
'

shell

Example Request Body

{
  "force": true,
  "scheduled_at": "2024-08-25T15:00:00Z",
  "strategy": "immediate_prorate",
  "subscription_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ],
  "target_plan_version": 0,
  "target_product_version": 0
}

json

Example Responses

{
  "data": {
    "skipped": [
      {
        "reason": "reason",
        "sub_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "upgraded": [
      {
        "new_version": 0,
        "sub_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ]
  }
}

json

application/json

Preview subscription prices

POST

https://api.kontier.eu/v1

/subscriptions/preview-prices

Resolves the effective per-line price for a candidate plan + items + customer combo without creating a subscription.

Preview subscription prices › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Preview subscription prices › Request Body

plan_id

string · uuid · required

as_of

string · date-time

Date to price for; omit to price for now. Folded to day granularity.

currency

string

customer_id

string · uuid

array | null

plan_version

integer · int64

Published plan version to price against; omit to price the plan's current head.

Preview subscription prices › Responses

object · required

POST/subscriptions/preview-prices

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/preview-prices \
  --header 'Content-Type: application/json' \
  --data '
{
  "as_of": "2024-08-25T15:00:00Z",
  "currency": "currency",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "items": [
    {
      "negotiated_tiers": [
        {
          "flat_amount": "49.5",
          "formula_driven": true,
          "unit_amount": "49.5",
          "up_to": "49.5"
        }
      ],
      "negotiated_unit_amount": "49.5",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": 5
    }
  ],
  "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "plan_version": 0
}
'

shell

Example Request Body

{
  "as_of": "2024-08-25T15:00:00Z",
  "currency": "currency",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "items": [
    {
      "negotiated_tiers": [
        {
          "flat_amount": "49.5",
          "formula_driven": true,
          "unit_amount": "49.5",
          "up_to": "49.5"
        }
      ],
      "negotiated_unit_amount": "49.5",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": 5
    }
  ],
  "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "plan_version": 0
}

json

Example Responses

{
  "data": {
    "currency": "currency",
    "lines": [
      {
        "catalog_tiers": [
          {
            "flat_amount": "49.5",
            "formula_driven": true,
            "unit_amount": "49.5",
            "up_to": "49.5"
          }
        ],
        "catalog_unit_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "currency": "currency",
        "error": "error",
        "included_quantity": 0,
        "pricing_model": "pricing_model",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "quantity": 0,
        "quantity_source": "quantity_source",
        "tax_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "tax_rate": "49.5",
        "tier_breakdown": [
          {
            "amount": "49.5",
            "lower_bound": "49.5",
            "quantity": "49.5",
            "tier_index": 0,
            "unit_price": "49.5",
            "upper_bound": "49.5"
          }
        ],
        "total_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "total_amount_with_tax": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_amount": {
          "currency": "EUR",
          "value": "49.5"
        }
      }
    ],
    "price_cadence_unit": "price_cadence_unit",
    "subtotal": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_total": {
      "currency": "EUR",
      "value": "49.5"
    },
    "total": {
      "currency": "EUR",
      "value": "49.5"
    }
  }
}

json

application/json

Get a subscription

GET

https://api.kontier.eu/v1

/subscriptions/{id}

Returns a subscription with its enrichment payload (MRR/ARR, attached promotions).

Get a subscription › path Parameters

id

string · uuid · required

Subscription UUID

Get a subscription › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a subscription › Responses

object · required

GET/subscriptions/{id}

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

shell

Example Responses

{
  "data": {
    "active_promotions": [
      {
        "discount_value": "discount_value",
        "effect_type": "effect_type",
        "expires_at": "2024-08-25T15:00:00Z",
        "name": "name",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "allowed_transitions": [
      "DRAFT"
    ],
    "arr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_renew": true,
    "billing_anchor_day": 0,
    "billing_interval_count": 0,
    "billing_interval_unit": "month",
    "billing_timing": "in_advance",
    "cancellation_reason": "USER_REQUEST",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "current_period_end": "2026-07-01",
    "current_period_start": "2026-07-01",
    "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "custom_fields": {
      "key": {}
    },
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "deviation": {
      "count": 0,
      "deviates": true,
      "kinds": [
        "string"
      ]
    },
    "display_name": "display_name",
    "drift": {
      "latest_version": 0,
      "versions_behind": 0
    },
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "items": [
      {
        "charge_span_count": 0,
        "charge_span_unit": "month",
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_applied": true,
        "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_source": "override_source",
        "price_key": "price_key",
        "pricing_model": "PACKAGE",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "quantity": 0,
        "quantity_adjustable": true,
        "quantity_source": "DECLARED",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "total_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_label": "unit_label",
        "unit_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "metadata": {
      "key": {}
    },
    "mrr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "name": "name",
    "next_billing_date": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "payment_terms_days": 0,
    "pending_checkout_session_id": "pending_checkout_session_id",
    "phases": [
      {
        "auto_transition": true,
        "completed_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "dunning_stage": "WARNED",
        "dunning_stage_at": "2024-08-25T15:00:00Z",
        "duration_unit": "day",
        "duration_value": 0,
        "end_at": "2024-08-25T15:00:00Z",
        "end_kind": "manual",
        "ends_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "phase_kind": "setup",
        "phase_order": 0,
        "started_at": "2024-08-25T15:00:00Z",
        "status": "PENDING",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_version": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_version": 0,
    "public_description": "public_description",
    "reference": "reference",
    "settings": {
      "default_proration_mode": "pro_rata",
      "line_grouping": "line_grouping",
      "price_resolution_policy": "price_resolution_policy"
    },
    "start_at": "2024-08-25T15:00:00Z",
    "start_trigger": "immediate",
    "started_at": "2024-08-25T15:00:00Z",
    "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
      }
    ],
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "version_change_strategy": "immediate_prorate",
    "version_track_mode": "pinned"
  }
}

json

application/json

Update a subscription's editable fields

PATCH

https://api.kontier.eu/v1

/subscriptions/{id}

Applies operator-editable fields (name, description, public_description, translations, metadata, custom_fields, settings) and the version-tracking configuration (version_track_mode pinned/latest + default version_change_strategy). Setting version_track_mode=latest requires a version_change_strategy. Version tracking is a preference, not a movement — a subscription.update Change with a version part actually moves the version. Lifecycle changes are Changes too (subscription.cancel / .pause / .resume).

Update a subscription's editable fields › path Parameters

id

string · uuid · required

Subscription UUID

Update a subscription's editable fields › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a subscription's editable fields › Request Body

billing_timing

string · enum

New invoice timing (in_advance/in_arrears); editable only while DRAFT, null leaves it unchanged.

Enum values:

in_advance

in_arrears

clear_settings

array | null · maxItems: 100

Setting keys to reset back to inherit (NULL the column); use to clear an override that Settings alone cannot.

object

Values for the org's configured custom fields.

description

string · maxLength: 2000

New internal operator-facing description; null leaves it unchanged.

object

Arbitrary caller-supplied key/value pairs; replaces the stored map.

name

string · maxLength: 200

New internal operator-facing name; null leaves it unchanged.

public_description

string · maxLength: 2000

New buyer-facing description; null leaves it unchanged.

object

Per-subscription billing setting overrides to set or change; null leaves them unchanged.

object

Locale-keyed overrides for name, description and public_description.

version_change_strategy

string

New default money policy for auto-upgrades; null leaves it unchanged.

version_track_mode

string

New version-track mode (pinned/latest); null leaves it unchanged.

Update a subscription's editable fields › Responses

object · required

PATCH/subscriptions/{id}

curl --request PATCH \
  --url https://api.kontier.eu/v1/subscriptions/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing_timing": "in_advance",
  "clear_settings": [
    "string"
  ],
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "public_description": "public_description",
  "settings": {
    "default_proration_mode": "pro_rata",
    "line_grouping": "line_grouping",
    "price_resolution_policy": "price_resolution_policy"
  },
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "version_change_strategy": "version_change_strategy",
  "version_track_mode": "version_track_mode"
}
'

shell

Example Request Body

{
  "billing_timing": "in_advance",
  "clear_settings": [
    "string"
  ],
  "custom_fields": {
    "key": {}
  },
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "public_description": "public_description",
  "settings": {
    "default_proration_mode": "pro_rata",
    "line_grouping": "line_grouping",
    "price_resolution_policy": "price_resolution_policy"
  },
  "translations": {
    "key": {
      "description": "description",
      "name": "name",
      "public_description": "public_description"
    }
  },
  "version_change_strategy": "version_change_strategy",
  "version_track_mode": "version_track_mode"
}

json

Example Responses

{
  "data": {
    "active_promotions": [
      {
        "discount_value": "discount_value",
        "effect_type": "effect_type",
        "expires_at": "2024-08-25T15:00:00Z",
        "name": "name",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "allowed_transitions": [
      "DRAFT"
    ],
    "arr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_renew": true,
    "billing_anchor_day": 0,
    "billing_interval_count": 0,
    "billing_interval_unit": "month",
    "billing_timing": "in_advance",
    "cancellation_reason": "USER_REQUEST",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "current_period_end": "2026-07-01",
    "current_period_start": "2026-07-01",
    "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "custom_fields": {
      "key": {}
    },
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "deviation": {
      "count": 0,
      "deviates": true,
      "kinds": [
        "string"
      ]
    },
    "display_name": "display_name",
    "drift": {
      "latest_version": 0,
      "versions_behind": 0
    },
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "items": [
      {
        "charge_span_count": 0,
        "charge_span_unit": "month",
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_applied": true,
        "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_source": "override_source",
        "price_key": "price_key",
        "pricing_model": "PACKAGE",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "quantity": 0,
        "quantity_adjustable": true,
        "quantity_source": "DECLARED",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "total_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_label": "unit_label",
        "unit_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "metadata": {
      "key": {}
    },
    "mrr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "name": "name",
    "next_billing_date": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "payment_terms_days": 0,
    "pending_checkout_session_id": "pending_checkout_session_id",
    "phases": [
      {
        "auto_transition": true,
        "completed_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "dunning_stage": "WARNED",
        "dunning_stage_at": "2024-08-25T15:00:00Z",
        "duration_unit": "day",
        "duration_value": 0,
        "end_at": "2024-08-25T15:00:00Z",
        "end_kind": "manual",
        "ends_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "phase_kind": "setup",
        "phase_order": 0,
        "started_at": "2024-08-25T15:00:00Z",
        "status": "PENDING",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_version": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_version": 0,
    "public_description": "public_description",
    "reference": "reference",
    "settings": {
      "default_proration_mode": "pro_rata",
      "line_grouping": "line_grouping",
      "price_resolution_policy": "price_resolution_policy"
    },
    "start_at": "2024-08-25T15:00:00Z",
    "start_trigger": "immediate",
    "started_at": "2024-08-25T15:00:00Z",
    "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
      }
    ],
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "version_change_strategy": "immediate_prorate",
    "version_track_mode": "pinned"
  }
}

json

application/json

Activate a subscription

POST

https://api.kontier.eu/v1

/subscriptions/{id}/activate

Activates a DRAFT subscription, or resumes one paused via a pause phase. For DRAFT subs this overrides the configured start trigger and starts immediately. (Status is DRAFT/ACTIVE/CANCELLED/EXPIRED; "paused" and "trialing" are phase kinds on an ACTIVE subscription, not statuses.)

Activate a subscription › path Parameters

id

string · uuid · required

Subscription UUID

Activate a subscription › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Activate a subscription › Responses

object · required

POST/subscriptions/{id}/activate

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/activate \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "active_promotions": [
      {
        "discount_value": "discount_value",
        "effect_type": "effect_type",
        "expires_at": "2024-08-25T15:00:00Z",
        "name": "name",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "allowed_transitions": [
      "DRAFT"
    ],
    "arr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_renew": true,
    "billing_anchor_day": 0,
    "billing_interval_count": 0,
    "billing_interval_unit": "month",
    "billing_timing": "in_advance",
    "cancellation_reason": "USER_REQUEST",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "current_period_end": "2026-07-01",
    "current_period_start": "2026-07-01",
    "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "custom_fields": {
      "key": {}
    },
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "deviation": {
      "count": 0,
      "deviates": true,
      "kinds": [
        "string"
      ]
    },
    "display_name": "display_name",
    "drift": {
      "latest_version": 0,
      "versions_behind": 0
    },
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "items": [
      {
        "charge_span_count": 0,
        "charge_span_unit": "month",
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_applied": true,
        "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_source": "override_source",
        "price_key": "price_key",
        "pricing_model": "PACKAGE",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "quantity": 0,
        "quantity_adjustable": true,
        "quantity_source": "DECLARED",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "total_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_label": "unit_label",
        "unit_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "metadata": {
      "key": {}
    },
    "mrr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "name": "name",
    "next_billing_date": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "payment_terms_days": 0,
    "pending_checkout_session_id": "pending_checkout_session_id",
    "phases": [
      {
        "auto_transition": true,
        "completed_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "dunning_stage": "WARNED",
        "dunning_stage_at": "2024-08-25T15:00:00Z",
        "duration_unit": "day",
        "duration_value": 0,
        "end_at": "2024-08-25T15:00:00Z",
        "end_kind": "manual",
        "ends_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "phase_kind": "setup",
        "phase_order": 0,
        "started_at": "2024-08-25T15:00:00Z",
        "status": "PENDING",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_version": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_version": 0,
    "public_description": "public_description",
    "reference": "reference",
    "settings": {
      "default_proration_mode": "pro_rata",
      "line_grouping": "line_grouping",
      "price_resolution_policy": "price_resolution_policy"
    },
    "start_at": "2024-08-25T15:00:00Z",
    "start_trigger": "immediate",
    "started_at": "2024-08-25T15:00:00Z",
    "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
      }
    ],
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "version_change_strategy": "immediate_prorate",
    "version_track_mode": "pinned"
  }
}

json

application/json

Get subscription allowance state

GET

https://api.kontier.eu/v1

/subscriptions/{id}/allowance

The current allowance state for each USAGE product in the subscription's plan.

Get subscription allowance state › path Parameters

id

string · uuid · required

Subscription UUID

Get subscription allowance state › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get subscription allowance state › Responses

object · required

GET/subscriptions/{id}/allowance

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

shell

Example Responses

{
  "data": {
    "current_period_end": "current_period_end",
    "current_period_start": "current_period_start",
    "products": [
      {
        "billable_usage": "49.5",
        "consumed_allowance": "49.5",
        "consumed_credits": "49.5",
        "consumed_plan": "49.5",
        "consumed_purchased": "49.5",
        "consumed_rollover": "49.5",
        "credit_allowance": "49.5",
        "credit_grants": [
          {
            "expires_at": "2024-08-25T15:00:00Z",
            "quantity": "49.5",
            "source": "source"
          }
        ],
        "declared": {
          "billable_quantity": 0,
          "included_quantity": 0,
          "quantity_held": 0,
          "unrealized_quantity": 0
        },
        "included_quantity_source": "included_quantity_source",
        "plan_allowance": "49.5",
        "plan_pin_quantity": "49.5",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "purchased_allowance": "49.5",
        "refresh_count": 0,
        "refresh_unit": "refresh_unit",
        "remaining_allowance": "49.5",
        "rollover_allowance": "49.5",
        "total_allowance": "49.5",
        "total_usage": "49.5",
        "unit_label": "unit_label"
      }
    ],
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get how a subscription differs from its plan

GET

https://api.kontier.eu/v1

/subscriptions/{id}/deviation

Every way the subscription departs from the plan version it is pinned to, with both sides of each comparison: operator-overridden included quantities, purchased quantities outside the plan's authored band, products the plan no longer carries, and entitlement kinds the plan disagrees with. A standard subscription answers 200 with deviates=false. Derived on every read — nothing is stored.

Get how a subscription differs from its plan › path Parameters

id

string · uuid · required

Subscription UUID

Get how a subscription differs from its plan › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get how a subscription differs from its plan › Responses

object · required

GET/subscriptions/{id}/deviation

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

shell

Example Responses

{
  "data": {
    "deviates": true,
    "entries": [
      {
        "actual_quantity": "49.5",
        "catalog_unit_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "kind": "kind",
        "negotiated_source": "negotiated_source",
        "negotiated_unit_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "plan_max_quantity": 0,
        "plan_min_quantity": 0,
        "plan_quantity": "49.5",
        "price_key": "price_key",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "source_quote_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "valid_from": "2024-08-25T15:00:00Z",
        "valid_to": "2024-08-25T15:00:00Z"
      }
    ],
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get a subscription's version-drift summary

GET

https://api.kontier.eu/v1

/subscriptions/{id}/drift

How many plan (or product) versions behind a subscription is, the latest active version, the next scheduled version (if any), and an upgradable_to list of candidate versions.

Get a subscription's version-drift summary › path Parameters

id

string · uuid · required

Subscription UUID

Get a subscription's version-drift summary › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a subscription's version-drift summary › Responses

object · required

GET/subscriptions/{id}/drift

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

shell

Example Responses

{
  "data": {
    "current_version": 0,
    "latest_published_at": "2024-08-25T15:00:00Z",
    "latest_scheduled_at": "2024-08-25T15:00:00Z",
    "latest_version": 0,
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "sub_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "track_mode": "track_mode",
    "upgradable_to": [
      {
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "lifecycle": "lifecycle",
        "version": 0
      }
    ],
    "versions_behind": 0
  }
}

json

application/json

List items on a subscription

GET

https://api.kontier.eu/v1

/subscriptions/{id}/items

Returns the subscription's current items: rows whose effective window is still open. Historical rows superseded by a quantity change or removal are excluded.

List items on a subscription › path Parameters

id

string · uuid · required

Subscription UUID

List items on a subscription › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List items on a subscription › Responses

array | null · required

object · required

GET/subscriptions/{id}/items

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

shell

Example Responses

{
  "data": [
    {
      "charge_span_count": 0,
      "charge_span_unit": "month",
      "created_at": "2024-08-25T15:00:00Z",
      "display_name": "display_name",
      "effective_from": "2024-08-25T15:00:00Z",
      "effective_to": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "override_applied": true,
      "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "override_source": "override_source",
      "price_key": "price_key",
      "pricing_model": "PACKAGE",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_name": "product_name",
      "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "quantity": 0,
      "quantity_adjustable": true,
      "quantity_source": "DECLARED",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "total_price": {
        "currency": "EUR",
        "value": "49.5"
      },
      "unit_label": "unit_label",
      "unit_price": {
        "currency": "EUR",
        "value": "49.5"
      },
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

List subscription phases

GET

https://api.kontier.eu/v1

/subscriptions/{id}/phases

Returns every phase of the subscription — pending, active, and completed. Phases are ENGINE state and are not authored: the chain is derived from the subscription's free_trial_days, and paused/dunning phases are written by the pause/resume and dunning operations. Unpaginated.

List subscription phases › path Parameters

id

string · uuid · required

Subscription UUID

List subscription phases › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List subscription phases › Responses

array | null · required

object · required

GET/subscriptions/{id}/phases

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

shell

Example Responses

{
  "data": [
    {
      "auto_transition": true,
      "completed_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "dunning_stage": "WARNED",
      "dunning_stage_at": "2024-08-25T15:00:00Z",
      "duration_unit": "day",
      "duration_value": 0,
      "end_at": "2024-08-25T15:00:00Z",
      "end_kind": "manual",
      "ends_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "phase_kind": "setup",
      "phase_order": 0,
      "started_at": "2024-08-25T15:00:00Z",
      "status": "PENDING",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

List a subscription's plan-version history

GET

https://api.kontier.eu/v1

/subscriptions/{id}/plan-version-history

Chronological pin-events for a subscription: each row records which plan/product version was pinned at which instant. Cursor-paginated (default 100, max 200 per page).

List a subscription's plan-version history › path Parameters

id

string · uuid · required

Subscription UUID

List a subscription's plan-version history › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List a subscription's plan-version history › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List a subscription's plan-version history › Responses

array | null · required

object · required

GET/subscriptions/{id}/plan-version-history

curl --request GET \
  --url https://api.kontier.eu/v1/subscriptions/:id/plan-version-history

shell

Example Responses

{
  "data": [
    {
      "change_reason": "change_reason",
      "created_at": "2024-08-25T15:00:00Z",
      "effective_from": "2024-08-25T15:00:00Z",
      "effective_to": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "plan_version": 0,
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "product_version": 0,
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Set a product's allowance-refresh cadence

PATCH

https://api.kontier.eu/v1

/subscriptions/{id}/products/{productId}/allowance-refresh

Overrides how often the included allowance pool refreshes for one product (e.g. daily). Both fields omitted clears the override (refreshes once per billing cycle).

Set a product's allowance-refresh cadence › path Parameters

id

string · uuid · required

Subscription UUID

productId

string · uuid · required

Product UUID

Set a product's allowance-refresh cadence › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Set a product's allowance-refresh cadence › Request Body

refresh_count

integer · int64

How often the included pool refreshes, as a count of refresh_unit; both fields null clears the override.

refresh_unit

string

Unit of the refresh cadence: day, week, month, year or billing_cycle; both fields null clears the override.

Set a product's allowance-refresh cadence › Responses

No Content

No data returned

Override a product's included quantity

PUT

https://api.kontier.eu/v1

/subscriptions/{id}/products/{productId}/included-quantity

Sets how many units are included for ONE subscription, overriding the plan version's pin. Works for any product the subscription carries, INCLUDING one whose plan pins no included quantity — the catalog authoring no baseline does not stop an operator authoring a number. The next invoice bills this number, and it survives a plan version bump (the subscription then reads as adjusted against the new version). 0 is a valid override meaning nothing is included; use DELETE to go back to the plan's number. 404 when the subscription does not carry the product at all. Rejected for a product configured as a durable credit pool, whose allowance is its balance.

Override a product's included quantity › path Parameters

id

string · uuid · required

Subscription UUID

productId

string · uuid · required

Product UUID

Override a product's included quantity › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Override a product's included quantity › Request Body

included_quantity

string · required

Units included for this subscription, as a non-negative decimal string. 0 is a valid override meaning nothing is included; to go back to the plan's number use DELETE instead.

Override a product's included quantity › Responses

No Content

No data returned

Drop a product's included-quantity override

DELETE

https://api.kontier.eu/v1

/subscriptions/{id}/products/{productId}/included-quantity

Removes the per-subscription override so the product follows its plan version's included quantity again, now and after every future publish.

Drop a product's included-quantity override › path Parameters

id

string · uuid · required

Subscription UUID

productId

string · uuid · required

Product UUID

Drop a product's included-quantity override › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Drop a product's included-quantity override › Responses

No Content

No data returned

Make a product a durable credit pool

PATCH

https://api.kontier.eu/v1

/subscriptions/{id}/products/{productId}/pool

Converts (or creates) the (subscription, product) entitlement into a durable POOL — a cross-period balance that drains as usage is metered. Clears any refresh cadence.

Make a product a durable credit pool › path Parameters

id

string · uuid · required

Subscription UUID

productId

string · uuid · required

Product UUID

Make a product a durable credit pool › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Make a product a durable credit pool › Request Body

unit_limit

string

Maximum pool balance in units, as a decimal string; null for no unit ceiling.

Make a product a durable credit pool › Responses

No Content

No data returned

List a subscription's booked proration entries

GET

https://api.kontier.eu/v1

/subscriptions/{id}/prorations

The booked proration ledger (credits/charges generated by quantity, plan, or version changes) in chronological order. Cursor-paginated (default 100, max 200 per page).

List a subscription's booked proration entries › path Parameters

id

string · uuid · required

Subscription UUID

List a subscription's booked proration entries › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List a subscription's booked proration entries › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List a subscription's booked proration entries › Responses

array | null · required

object · required

GET/subscriptions/{id}/prorations

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

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "applied": true,
      "change_date": "2024-08-25T15:00:00Z",
      "currency": "currency",
      "description": "description",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_line_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "period_end": "2026-07-01",
      "period_start": "2026-07-01",
      "proration_type": "proration_type"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Simulate proposed subscription changes

POST

https://api.kontier.eu/v1

/subscriptions/{id}/simulate

Returns a dry-run preview (proration, MRR delta, …) for a candidate change set without persisting. The change set composes: add_items, remove_items, new_plan_id, change_quantity and change_version may be sent together. change_quantity and change_version price the same math a subscription.update Change books (items[{op:quantity}] and version) and require an ACTIVE subscription. A change_version with a deferred strategy (next_period / at_phase_change) books nothing in the current period and honestly prices to zero.

Simulate proposed subscription changes › path Parameters

id

string · uuid · required

Subscription UUID

Simulate proposed subscription changes › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Simulate proposed subscription changes › Request Body

array | null · maxItems: 500

Items to add in this dry run.

array | null · maxItems: 500

Quantity restatements to price; each entry prices as one cross-quantity diff.

object

A version repin to price onto another plan/product version.

new_plan_id

string · uuid

Plan to retarget the subscription onto in this dry run; null leaves the plan unchanged.

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

array | null · maxItems: 500

Items to remove in this dry run.

Simulate proposed subscription changes › Responses

object · required

POST/subscriptions/{id}/simulate

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/simulate \
  --header 'Content-Type: application/json' \
  --data '
{
  "add_items": [
    {
      "charge_span_count": 0,
      "charge_span_unit": "month",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "proration_mode": "pro_rata",
      "quantity": 5
    }
  ],
  "change_quantity": [
    {
      "new_quantity": 0,
      "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "change_version": {
    "strategy": "strategy",
    "target_latest": true,
    "target_version": 0
  },
  "new_plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "remove_items": [
    {
      "proration_mode": "proration_mode",
      "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ]
}
'

shell

Example Request Body

{
  "add_items": [
    {
      "charge_span_count": 0,
      "charge_span_unit": "month",
      "price_key": "price_key",
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "proration_mode": "pro_rata",
      "quantity": 5
    }
  ],
  "change_quantity": [
    {
      "new_quantity": 0,
      "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "change_version": {
    "strategy": "strategy",
    "target_latest": true,
    "target_version": 0
  },
  "new_plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "remove_items": [
    {
      "proration_mode": "proration_mode",
      "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ]
}

json

Example Responses

{
  "data": {
    "charges": {
      "currency": "EUR",
      "value": "49.5"
    },
    "credits": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "line_items": [
      {
        "amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "days_remaining": 0,
        "description": "description",
        "new_quantity": 0,
        "old_quantity": 0,
        "subscription_item_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "tax_amount": {
          "currency": "EUR",
          "value": "49.5"
        },
        "tax_rate": "49.5",
        "type": "type"
      }
    ],
    "net_impact": {
      "currency": "EUR",
      "value": "49.5"
    },
    "period_end": "period_end",
    "period_start": "period_start",
    "tax_total": {
      "currency": "EUR",
      "value": "49.5"
    },
    "total": {
      "currency": "EUR",
      "value": "49.5"
    }
  }
}

json

application/json

Get the subscription's forward timeline

GET

https://api.kontier.eu/v1

/subscriptions/{id}/timeline

ONE ordered answer to "what happens next", unioned from every time rail a subscription has: booked changes (including those filed against its lines and its agreements), phase boundaries, the agreed term end and its notice, negotiated price and ramp edges, item windows, scheduled catalogue publishes and the version pins that hold lines back from them, billing milestones, the renewal and auto-renew clocks, dunning escalation, allowance refreshes and promotion expiries. Every event carries a certainty — fixed (a wall-clock instant), anchored (follows a moving anchor such as period_end) or derived (computed from today's state and shown as expected) — so a prediction is never presented as a booking. Nothing is returned after the subscription's ending, and the ending itself is both the last event and the embedded ending field, resolved by the same rule GET /subscriptions/{id} uses. Default window: now to the ending, or 18 months. Unpaginated; limit caps the events and sets truncated.

Get the subscription's forward timeline › path Parameters

id

string · uuid · required

Subscription UUID

Get the subscription's forward timeline › query Parameters

from

string

Start of the window, INCLUSIVE. RFC 3339 (2026-05-01T00:00:00Z) or a bare date (2026-05-01). Defaults to now.

to

string

End of the window, EXCLUSIVE — the range is half-open [from, to). Defaults to the subscription's ending, or 18 months out when nothing stops it.

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

Get the subscription's forward timeline › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the subscription's forward timeline › Responses

object · required

GET/subscriptions/{id}/timeline

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

shell

Example Responses

{
  "data": {
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "events": [
      {
        "actions": [
          {
            "id": "id",
            "target": {
              "display_name": "display_name",
              "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
              "kind": "kind",
              "reference": "reference"
            }
          }
        ],
        "at": "2024-08-25T15:00:00Z",
        "certainty": "fixed",
        "kind": "trial_ends",
        "money_delta": {
          "currency": "EUR",
          "value": "49.5"
        },
        "ref": "ref",
        "reversible": true,
        "source": "change",
        "subject": {
          "display_name": "display_name",
          "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
          "kind": "kind",
          "reference": "reference"
        },
        "title_key": "title_key",
        "title_params": {
          "key": "string"
        }
      }
    ],
    "generated_at": "2024-08-25T15:00:00Z",
    "truncated": true,
    "window": {
      "from": "2024-08-25T15:00:00Z",
      "to": "2024-08-25T15:00:00Z"
    }
  }
}

json

application/json

Grant usage credits to a subscription

POST

https://api.kontier.eu/v1

/subscriptions/{id}/usage-credits

Grants additional usage credits to the subscription. For a product configured as a durable credit POOL this writes a purchased entitlement grant; otherwise the credits are injected via a single-use promotion redemption and applied at the next invoice run. Distinct from POST /wallets/{id}/topup, which credits money to a wallet.

Grant usage credits to a subscription › path Parameters

id

string · uuid · required

Subscription UUID

Grant usage credits to a subscription › Headers

Idempotency-Key

string · required

Threaded into the grant as its dedup token: the same key collapses onto one grant, a new key grants again.

X-Workspace-Id

string

Workspace UUID or slug.

Grant usage credits to a subscription › Request Body

product_id

string · uuid · required

Product to grant usage against.

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

quantity

string · pattern: ^-?\d+(\.\d+)?$ · required

Usage quantity to grant (metered units, NOT money).

Example: 49.5

description

string · maxLength: 2000

Optional note recorded on the grant.

Grant usage credits to a subscription › Responses

Created

object · required

POST/subscriptions/{id}/usage-credits

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/usage-credits \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "description": "description",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "quantity": "49.5"
}
'

shell

Example Request Body

{
  "description": "description",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "quantity": "49.5"
}

json

Example Responses

{
  "data": {
    "grant": {
      "charge_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "consumed_quantity": "49.5",
      "created_at": "2024-08-25T15:00:00Z",
      "dedup_key": "dedup_key",
      "effective_from": "2024-08-25T15:00:00Z",
      "entitlement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "expires_at": "2024-08-25T15:00:00Z",
      "granted_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "nature": "nature",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "origin": "origin",
      "origin_ref_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "price_key": "price_key",
      "quantity": "49.5",
      "reason": "reason",
      "revoked_at": "2024-08-25T15:00:00Z",
      "revoked_reason": "revoked_reason",
      "source": "source",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  }
}

json

application/json

Withdraw a subscription (EU 14-day right of withdrawal)

POST

https://api.kontier.eu/v1

/subscriptions/{id}/withdraw

Cancels a CONSUMER subscription still inside the EU 14-day right-of-withdrawal window (Directive 2011/83/EU) with a full refund. Returns NOT_ELIGIBLE_FOR_WITHDRAWAL when ineligible.

Withdraw a subscription (EU 14-day right of withdrawal) › path Parameters

id

string · uuid · required

Subscription UUID

Withdraw a subscription (EU 14-day right of withdrawal) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Withdraw a subscription (EU 14-day right of withdrawal) › Responses

object · required

POST/subscriptions/{id}/withdraw

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/withdraw \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "active_promotions": [
      {
        "discount_value": "discount_value",
        "effect_type": "effect_type",
        "expires_at": "2024-08-25T15:00:00Z",
        "name": "name",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "allowed_transitions": [
      "DRAFT"
    ],
    "arr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_renew": true,
    "billing_anchor_day": 0,
    "billing_interval_count": 0,
    "billing_interval_unit": "month",
    "billing_timing": "in_advance",
    "cancellation_reason": "USER_REQUEST",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "current_period_end": "2026-07-01",
    "current_period_start": "2026-07-01",
    "current_phase_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "custom_fields": {
      "key": {}
    },
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "deviation": {
      "count": 0,
      "deviates": true,
      "kinds": [
        "string"
      ]
    },
    "display_name": "display_name",
    "drift": {
      "latest_version": 0,
      "versions_behind": 0
    },
    "ending": {
      "agreement_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "at": "2024-08-25T15:00:00Z",
      "kind": "RUNS_UNTIL_CANCELLED"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "items": [
      {
        "charge_span_count": 0,
        "charge_span_unit": "month",
        "created_at": "2024-08-25T15:00:00Z",
        "display_name": "display_name",
        "effective_from": "2024-08-25T15:00:00Z",
        "effective_to": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_applied": true,
        "override_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "override_source": "override_source",
        "price_key": "price_key",
        "pricing_model": "PACKAGE",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_name": "product_name",
        "product_version_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "quantity": 0,
        "quantity_adjustable": true,
        "quantity_source": "DECLARED",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "total_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "unit_label": "unit_label",
        "unit_price": {
          "currency": "EUR",
          "value": "49.5"
        },
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ],
    "metadata": {
      "key": {}
    },
    "mrr": {
      "currency": "EUR",
      "value": "49.5"
    },
    "name": "name",
    "next_billing_date": "2024-08-25T15:00:00Z",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "payment_terms_days": 0,
    "pending_checkout_session_id": "pending_checkout_session_id",
    "phases": [
      {
        "auto_transition": true,
        "completed_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "dunning_stage": "WARNED",
        "dunning_stage_at": "2024-08-25T15:00:00Z",
        "duration_unit": "day",
        "duration_value": 0,
        "end_at": "2024-08-25T15:00:00Z",
        "end_kind": "manual",
        "ends_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "phase_kind": "setup",
        "phase_order": 0,
        "started_at": "2024-08-25T15:00:00Z",
        "status": "PENDING",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "plan_version": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_version": 0,
    "public_description": "public_description",
    "reference": "reference",
    "settings": {
      "default_proration_mode": "pro_rata",
      "line_grouping": "line_grouping",
      "price_resolution_policy": "price_resolution_policy"
    },
    "start_at": "2024-08-25T15:00:00Z",
    "start_trigger": "immediate",
    "started_at": "2024-08-25T15:00:00Z",
    "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
      }
    ],
    "translations": {
      "key": {
        "description": "description",
        "name": "name",
        "public_description": "public_description"
      }
    },
    "updated_at": "2024-08-25T15:00:00Z",
    "version_change_strategy": "immediate_prorate",
    "version_track_mode": "pinned"
  }
}

json

application/json

Customers Invoices