Billing Milestones

Endpointhttps://api.kontorion.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 billing milestones

GET

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones

Returns a paginated list of billing milestones for a subscription

List billing milestones › path Parameters

subscriptionId

string · required

Subscription UUID

List billing milestones › query Parameters

limit

integer

Page size

cursor

string

Pagination cursor

List billing milestones › Responses

Milestones with pagination

object[]

object

GET/subscriptions/{subscriptionId}/milestones

curl --request GET \
  --url https://api.kontorion.eu/v1/subscriptions/:subscriptionId/milestones

shell

Example Responses

{
  "milestones": [
    {
      "created_at": "created_at",
      "description": "description",
      "id": "id",
      "invoice_id": "invoice_id",
      "is_overdue": true,
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "organization_id",
      "percentage": 0,
      "product_id": "product_id",
      "status": "PENDING",
      "subscription_id": "subscription_id",
      "trigger_date": "trigger_date",
      "trigger_type": "MANUAL",
      "triggered_at": "triggered_at",
      "updated_at": "updated_at"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a billing milestone

POST

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones

Creates a new billing milestone for a subscription

Create a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

Create a billing milestone › Request Body

description

string

object

name

string

percentage

number

product_id

string

subscription_id

string

trigger_date

string

trigger_type

string · enum

Enum values:

MANUAL

DATE

EVENT

Create a billing milestone › Responses

Wrapped in data envelope

object

POST/subscriptions/{subscriptionId}/milestones

curl --request POST \
  --url https://api.kontorion.eu/v1/subscriptions/:subscriptionId/milestones \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "percentage": 0,
  "product_id": "product_id",
  "subscription_id": "subscription_id",
  "trigger_date": "trigger_date",
  "trigger_type": "MANUAL"
}
'

shell

Example Request Body

{
  "description": "description",
  "metadata": {
    "key": {}
  },
  "name": "name",
  "percentage": 0,
  "product_id": "product_id",
  "subscription_id": "subscription_id",
  "trigger_date": "trigger_date",
  "trigger_type": "MANUAL"
}

json

Example Responses

{
  "key": {
    "milestone": {
      "created_at": "created_at",
      "description": "description",
      "id": "id",
      "invoice_id": "invoice_id",
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "organization_id",
      "percentage": 0,
      "product_id": "product_id",
      "status": "PENDING",
      "subscription_id": "subscription_id",
      "trigger_date": "trigger_date",
      "trigger_type": "MANUAL",
      "triggered_at": "triggered_at",
      "updated_at": "updated_at"
    }
  }
}

json

application/json

Get a billing milestone

GET

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones/{id}

Returns a single billing milestone by ID

Get a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

id

string · required

Milestone UUID

Get a billing milestone › Responses

Wrapped in data envelope

object

GET/subscriptions/{subscriptionId}/milestones/{id}

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

shell

Example Responses

{
  "key": {
    "milestone": {
      "created_at": "created_at",
      "description": "description",
      "id": "id",
      "invoice_id": "invoice_id",
      "metadata": {
        "key": {}
      },
      "name": "name",
      "organization_id": "organization_id",
      "percentage": 0,
      "product_id": "product_id",
      "status": "PENDING",
      "subscription_id": "subscription_id",
      "trigger_date": "trigger_date",
      "trigger_type": "MANUAL",
      "triggered_at": "triggered_at",
      "updated_at": "updated_at"
    }
  }
}

json

application/json

Trigger a billing milestone

POST

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones/{id}/trigger

Triggers a billing milestone, generating the associated invoice or charge

Trigger a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

id

string · required

Milestone UUID

Trigger a billing milestone › Responses

Wrapped in data envelope

Scheduled Changes Dunning

List billing milestones

GET

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones

Returns a paginated list of billing milestones for a subscription

List billing milestones › path Parameters

subscriptionId

string · required

Subscription UUID

List billing milestones › query Parameters

limit

integer

Page size

cursor

string

Pagination cursor

List billing milestones › Responses

Milestones with pagination

object[]

object

Create a billing milestone

POST

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones

Creates a new billing milestone for a subscription

Create a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

Create a billing milestone › Request Body

description

string

object

name

string

percentage

number

product_id

string

subscription_id

string

trigger_date

string

trigger_type

string · enum

Enum values:

MANUAL

DATE

EVENT

Create a billing milestone › Responses

Wrapped in data envelope

object

Get a billing milestone

GET

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones/{id}

Returns a single billing milestone by ID

Get a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

id

string · required

Milestone UUID

Get a billing milestone › Responses

Wrapped in data envelope

object

Trigger a billing milestone

POST

https://api.kontorion.eu/v1

/subscriptions/{subscriptionId}/milestones/{id}/trigger

Triggers a billing milestone, generating the associated invoice or charge

Trigger a billing milestone › path Parameters

subscriptionId

string · required

Subscription UUID

id

string · required

Milestone UUID

Trigger a billing milestone › Responses

Wrapped in data envelope