Billing Milestones

Endpointhttps://api.kontier.eu/v1

Billing milestones are percentage-based checkpoints tied to a subscription's product delivery. They're designed for project-based or milestone-based billing - where charges are triggered when specific deliverables are completed rather than on a recurring schedule.

Example: A consulting engagement billed 25% at kickoff, 50% at mid-point, and 25% at completion.

Key concepts:

Trigger type - manual (you mark it complete) or date (triggers automatically at a scheduled date)
Percentage - the fraction of total contract value to invoice when this milestone triggers
Status - pending, triggered, or invoiced

List milestone plans

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestone-plans

Every milestone plan on the subscription with its instalments and the percentage of the price still unallocated. A plan is authored by scheduling a milestone_plan.create change; its instalments are edited with milestone.update and milestone.cancel.

List milestone plans › path Parameters

id

string · uuid · required

Subscription UUID

List milestone plans › 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 milestone plans › Responses

object · required

GET/subscriptions/{id}/milestone-plans

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

shell

Example Responses

{
  "data": {
    "plans": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "currency": "currency",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "milestones": [
          {
            "cancel_reason": "cancel_reason",
            "cancelled_at": "2024-08-25T15:00:00Z",
            "created_at": "2024-08-25T15:00:00Z",
            "description": "description",
            "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "is_overdue": true,
            "metadata": {
              "key": {}
            },
            "name": "name",
            "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "percentage": "49.5",
            "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "position": 0,
            "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "status": "status",
            "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
            "title": "title",
            "trigger_date": "2026-07-01",
            "trigger_type": "trigger_type",
            "triggered_at": "2024-08-25T15:00:00Z",
            "updated_at": "2024-08-25T15:00:00Z",
            "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
          }
        ],
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "remaining_percentage": "remaining_percentage",
        "source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "source_kind": "source_kind",
        "status": "status",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "title": "title",
        "updated_at": "2024-08-25T15:00:00Z",
        "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ]
  }
}

json

application/json

Get a milestone plan

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestone-plans/{planId}

One milestone plan with its instalments in order and the percentage of the price still unallocated.

Get a milestone plan › path Parameters

id

string · uuid · required

Subscription UUID

planId

string · uuid · required

Milestone plan UUID

Get a milestone plan › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a milestone plan › Responses

object · required

GET/subscriptions/{id}/milestone-plans/{planId}

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

shell

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "milestones": [
      {
        "cancel_reason": "cancel_reason",
        "cancelled_at": "2024-08-25T15:00:00Z",
        "created_at": "2024-08-25T15:00:00Z",
        "description": "description",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "is_overdue": true,
        "metadata": {
          "key": {}
        },
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "percentage": "49.5",
        "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "position": 0,
        "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "status": "status",
        "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "title": "title",
        "trigger_date": "2026-07-01",
        "trigger_type": "trigger_type",
        "triggered_at": "2024-08-25T15:00:00Z",
        "updated_at": "2024-08-25T15:00:00Z",
        "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "remaining_percentage": "remaining_percentage",
    "source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "source_kind": "source_kind",
    "status": "status",
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "title": "title",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List billing milestones

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestones

Every billing milestone on the subscription, newest first — the flat list across all its milestone plans, plus any standalone milestones. Use the milestone-plans routes to read them grouped by plan with the remaining percentage.

List billing milestones › path Parameters

id

string · uuid · required

Subscription UUID

List billing milestones › 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

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List billing milestones › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List billing milestones › Responses

array | null · required

object · required

GET/subscriptions/{id}/milestones

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

shell

Example Responses

{
  "data": [
    {
      "cancel_reason": "cancel_reason",
      "cancelled_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_overdue": true,
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "percentage": "49.5",
      "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "position": 0,
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "status": "status",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "title": "title",
      "trigger_date": "2026-07-01",
      "trigger_type": "trigger_type",
      "triggered_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a standalone billing milestone

POST

https://api.kontier.eu/v1

/subscriptions/{id}/milestones

Creates one milestone with no plan behind it. Its percentage is measured against the other plan-less milestones on the same (subscription, product) pair. To author a whole plan — the 30/40/30 — schedule a milestone_plan.create change instead: it validates the instalments together and gives them a plan to belong to.

Create a standalone billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

Create a standalone billing milestone › 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 standalone billing milestone › Request Body

name

string · maxLength: 200 · required

Operator-facing milestone name; required.

percentage

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

Fraction of the resolved price to bill, as a decimal in (0,1] (e.g. 0.25 = 25%). NOT money.

Example: 49.5

product_id

string · uuid · required

The product whose resolved price a fraction is billed; required.

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

trigger_type

string · required

What fires the milestone: MANUAL (operator triggers) or DATE (fires on trigger_date).

description

string · maxLength: 2000

Optional operator-facing description of the milestone.

object

Arbitrary caller-supplied key/value pairs.

trigger_date

string · date

Date the milestone fires; required when trigger_type is DATE.

Example: 2026-07-01

Create a standalone billing milestone › Responses

Created

object · required

POST/subscriptions/{id}/milestones

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/milestones \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "percentage": "49.5",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "trigger_date": "2026-07-01",
  "trigger_type": "trigger_type"
}
'

shell

Example Request Body

{
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "percentage": "49.5",
  "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "trigger_date": "2026-07-01",
  "trigger_type": "trigger_type"
}

json

Example Responses

{
  "data": {
    "cancel_reason": "cancel_reason",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_overdue": true,
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "percentage": "49.5",
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "position": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "status": "status",
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "title": "title",
    "trigger_date": "2026-07-01",
    "trigger_type": "trigger_type",
    "triggered_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get a billing milestone

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestones/{milestoneId}

Get a billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

milestoneId

string · uuid · required

Milestone UUID

Get a billing milestone › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a billing milestone › Responses

object · required

GET/subscriptions/{id}/milestones/{milestoneId}

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

shell

Example Responses

{
  "data": {
    "cancel_reason": "cancel_reason",
    "cancelled_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "description": "description",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_overdue": true,
    "metadata": {
      "key": {}
    },
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "percentage": "49.5",
    "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "position": 0,
    "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "status": "status",
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "title": "title",
    "trigger_date": "2026-07-01",
    "trigger_type": "trigger_type",
    "triggered_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Trigger a billing milestone

POST

https://api.kontier.eu/v1

/subscriptions/{id}/milestones/{milestoneId}/trigger

Fires the milestone and mints its invoice. Exactly once: a concurrent trigger, the hourly sweep and the milestone's own dated job all claim the same row and only one of them can win. The invoice is a DRAFT unless invoice_now is set, and the response says whether it was actually finalised.

Trigger a billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

milestoneId

string · uuid · required

Milestone UUID

Trigger a billing milestone › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Trigger a billing milestone › Request Body

invoice_now

boolean

Finalise the invoice this trigger mints instead of leaving it as a draft. The response says whether it actually was finalised.

Trigger a billing milestone › Responses

object · required

POST/subscriptions/{id}/milestones/{milestoneId}/trigger

curl --request POST \
  --url https://api.kontier.eu/v1/subscriptions/:id/milestones/:milestoneId/trigger \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "invoice_now": true
}
'

shell

Example Request Body

{
  "invoice_now": true
}

json

Example Responses

{
  "data": {
    "invoice_finalized": true,
    "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "milestone": {
      "cancel_reason": "cancel_reason",
      "cancelled_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "description": "description",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_overdue": true,
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "percentage": "49.5",
      "plan_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "position": 0,
      "product_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "status": "status",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "title": "title",
      "trigger_date": "2026-07-01",
      "trigger_type": "trigger_type",
      "triggered_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    },
    "warning": "warning"
  }
}

json

application/json

Subscription Add-Ons Webhook Secrets

List milestone plans

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestone-plans

List milestone plans › path Parameters

id

string · uuid · required

Subscription UUID

List milestone plans › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List milestone plans › Responses

object · required

Get a milestone plan

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestone-plans/{planId}

One milestone plan with its instalments in order and the percentage of the price still unallocated.

Get a milestone plan › path Parameters

id

string · uuid · required

Subscription UUID

planId

string · uuid · required

Milestone plan UUID

Get a milestone plan › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a milestone plan › Responses

object · required

List billing milestones

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestones

List billing milestones › path Parameters

id

string · uuid · required

Subscription UUID

List billing milestones › 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 billing milestones › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List billing milestones › Responses

array | null · required

object · required

Create a standalone billing milestone

POST

https://api.kontier.eu/v1

/subscriptions/{id}/milestones

Create a standalone billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

Create a standalone billing milestone › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a standalone billing milestone › Request Body

name

string · maxLength: 200 · required

Operator-facing milestone name; required.

percentage

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

Fraction of the resolved price to bill, as a decimal in (0,1] (e.g. 0.25 = 25%). NOT money.

Example: 49.5

product_id

string · uuid · required

The product whose resolved price a fraction is billed; required.

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

trigger_type

string · required

What fires the milestone: MANUAL (operator triggers) or DATE (fires on trigger_date).

description

string · maxLength: 2000

Optional operator-facing description of the milestone.

object

Arbitrary caller-supplied key/value pairs.

trigger_date

string · date

Date the milestone fires; required when trigger_type is DATE.

Example: 2026-07-01

Create a standalone billing milestone › Responses

Created

object · required

Get a billing milestone

GET

https://api.kontier.eu/v1

/subscriptions/{id}/milestones/{milestoneId}

Get a billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

milestoneId

string · uuid · required

Milestone UUID

Get a billing milestone › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a billing milestone › Responses

object · required

Trigger a billing milestone

POST

https://api.kontier.eu/v1

/subscriptions/{id}/milestones/{milestoneId}/trigger

Trigger a billing milestone › path Parameters

id

string · uuid · required

Subscription UUID

milestoneId

string · uuid · required

Milestone UUID

Trigger a billing milestone › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Trigger a billing milestone › Request Body

invoice_now

boolean

Finalise the invoice this trigger mints instead of leaving it as a draft. The response says whether it actually was finalised.

Trigger a billing milestone › Responses

object · required