Tags

Endpointhttps://api.kontorion.eu/v1

Org-defined labels and their assignment to customers, products, plans, subscriptions, invoices, and credit notes.

Add tags to a credit-note (additive)

POST

https://api.kontorion.eu/v1

/credit-notes/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the credit-note resource itself (its tags field).

Add tags to a credit-note (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a credit-note (additive) › 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

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.

Add tags to a credit-note (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a credit-note (additive) › Responses

array | null · required

POST/credit-notes/{id}/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/credit-notes/:id/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}
'

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a credit-note

DELETE

https://api.kontorion.eu/v1

/credit-notes/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a credit-note › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a credit-note › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a credit-note › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a credit-note › Responses

No Content

No data returned

Add tags to a customer (additive)

POST

https://api.kontorion.eu/v1

/customers/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the customer resource itself (its tags field).

Add tags to a customer (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a customer (additive) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add tags to a customer (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a customer (additive) › Responses

array | null · required

POST/customers/{id}/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/customers/:id/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}
'

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a customer

DELETE

https://api.kontorion.eu/v1

/customers/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a customer › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a customer › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a customer › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a customer › Responses

No Content

No data returned

Add tags to a invoice (additive)

POST

https://api.kontorion.eu/v1

/invoices/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the invoice resource itself (its tags field).

Add tags to a invoice (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a invoice (additive) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add tags to a invoice (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a invoice (additive) › Responses

array | null · required

POST/invoices/{id}/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/invoices/:id/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}
'

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a invoice

DELETE

https://api.kontorion.eu/v1

/invoices/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a invoice › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a invoice › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a invoice › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a invoice › Responses

No Content

No data returned

Add tags to a plan (additive)

POST

https://api.kontorion.eu/v1

/plans/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the plan resource itself (its tags field).

Add tags to a plan (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a plan (additive) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add tags to a plan (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a plan (additive) › Responses

array | null · required

POST/plans/{id}/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/plans/:id/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}
'

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a plan

DELETE

https://api.kontorion.eu/v1

/plans/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a plan › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a plan › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a plan › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a plan › Responses

No Content

No data returned

Add tags to a product (additive)

POST

https://api.kontorion.eu/v1

/products/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the product resource itself (its tags field).

Add tags to a product (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a product (additive) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add tags to a product (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a product (additive) › Responses

array | null · required

POST/products/{id}/tags

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

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a product

DELETE

https://api.kontorion.eu/v1

/products/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a product › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a product › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a product › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a product › Responses

No Content

No data returned

Add tags to a subscription (additive)

POST

https://api.kontorion.eu/v1

/subscriptions/{id}/tags

Applies the given tag IDs to the resource without removing existing tags. Returns the resulting set of tags. The current tag state also rides on the subscription resource itself (its tags field).

Add tags to a subscription (additive) › path Parameters

id

string · uuid · required

Resource UUID

Add tags to a subscription (additive) › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add tags to a subscription (additive) › Request Body

tag_ids

array | null · maxItems: 100

Add tags to a subscription (additive) › Responses

array | null · required

POST/subscriptions/{id}/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/subscriptions/:id/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}
'

shell

Example Request Body

{
  "tag_ids": [
    "0f8fad5b-d9cb-469f-a165-70867728950e"
  ]
}

json

Example Responses

{
  "data": [
    {
      "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
    }
  ]
}

json

application/json

Remove tags from a subscription

DELETE

https://api.kontorion.eu/v1

/subscriptions/{id}/tags

Detaches the tag IDs given in the tag_ids query parameter from the resource in one call. Other tags on the entity are unaffected; already-absent ids are ignored.

Remove tags from a subscription › path Parameters

id

string · uuid · required

Resource UUID

Remove tags from a subscription › query Parameters

tag_ids

array | null · maxItems: 100 · required

Tag UUIDs to remove

Remove tags from a subscription › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove tags from a subscription › Responses

No Content

No data returned

GET

https://api.kontorion.eu/v1

/tags

Returns a paginated list of tags. Filters use the unified field.op=value grammar; see /docs/pagination for the operator set. The archived state and usage-count toggle stay outside the grammar as control flags (see parameter descriptions).

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.

name

string

Filter by name; supports eq and contains operators

entity_type

string

Filter by entity type; supports eq and in operators

color

string

Filter by color; supports eq and in operators

created_at

string

Filter by created_at; supports eq, gt, gte, lt, lte operators

updated_at

string

Filter by updated_at; supports eq, gt, gte, lt, lte operators

archived

string

Tri-mode archived flag: true (include archived), only (only archived). Default returns active rows only.

include

string

Comma-separated includes. Currently supports usage_count to add the count of taggings per tag.

X-Workspace-Id

string

Workspace UUID or slug.

array | null · required

object · required

GET/tags

curl --request GET \
  --url https://api.kontorion.eu/v1/tags

shell

Example Responses

{
  "data": [
    {
      "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
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a tag

POST

https://api.kontorion.eu/v1

/tags

Creates a new tag scoped to the calling organization.

Create a tag › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a tag › Request Body

color

string

Optional display color as a #RRGGBB hex string.

description

string · maxLength: 500

Optional free-text description of the tag's purpose.

entity_type

string · enum

Entity kind the tag applies to: CUSTOMER, SUBSCRIPTION, PRODUCT, PLAN, INVOICE, or CREDIT_NOTE.

Enum values:

CUSTOMER

SUBSCRIPTION

PRODUCT

PLAN

INVOICE

CREDIT_NOTE

name

string · maxLength: 100

Display name; normalized (NFKC, trimmed, collapsed whitespace) and unique per (organization, entity_type).

Create a tag › Responses

Created

object · required

POST/tags

curl --request POST \
  --url https://api.kontorion.eu/v1/tags \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "color": "color",
  "description": "description",
  "entity_type": "CUSTOMER",
  "name": "name"
}
'

shell

Example Request Body

{
  "color": "color",
  "description": "description",
  "entity_type": "CUSTOMER",
  "name": "name"
}

json

Example Responses

{
  "data": {
    "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
  }
}

json

application/json

Get a tag

GET

https://api.kontorion.eu/v1

/tags/{id}

Returns a single tag by UUID.

Get a tag › path Parameters

id

string · uuid · required

Tag UUID

Get a tag › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a tag › Responses

object · required

Soft-delete a tag

DELETE

https://api.kontorion.eu/v1

/tags/{id}

Marks the tag deleted and cascades to drop all taggings that referenced it. Fails with 409 when the tag is still referenced by segment rules or promotion conditions - remove those references first.

Soft-delete a tag › path Parameters

id

string · uuid · required

Tag UUID

Soft-delete a tag › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Soft-delete a tag › Responses

No Content

No data returned

Update a tag

PATCH

https://api.kontorion.eu/v1

/tags/{id}

Applies partial updates to a tag. Setting archived: true archives the tag; passing archived: false un-archives. Setting description or color to an empty string clears the column.

Update a tag › path Parameters

id

string · uuid · required

Tag UUID

Update a tag › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a tag › Request Body

archived

boolean

Set true to archive the tag or false to restore it; omitted leaves it unchanged.

color

string

New display color as #RRGGBB; omitted leaves it unchanged.

description

string · maxLength: 500

New description; omitted leaves it unchanged.

name

string · maxLength: 100

New display name; omitted leaves it unchanged.

Update a tag › Responses

object · required

PATCH/tags/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/tags/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "archived": true,
  "color": "color",
  "description": "description",
  "name": "name"
}
'

shell

Example Request Body

{
  "archived": true,
  "color": "color",
  "description": "description",
  "name": "name"
}

json

Example Responses

{
  "data": {
    "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
  }
}

json

application/json

FX Accounting

Tags

Add tags to a credit-note (additive)

Add tags to a credit-note (additive) › path Parameters

Add tags to a credit-note (additive) › Headers

Add tags to a credit-note (additive) › Request Body

Add tags to a credit-note (additive) › Responses

Remove tags from a credit-note

Remove tags from a credit-note › path Parameters

Remove tags from a credit-note › query Parameters

Remove tags from a credit-note › Headers

Remove tags from a credit-note › Responses

Add tags to a customer (additive)

Add tags to a customer (additive) › path Parameters

Add tags to a customer (additive) › Headers

Add tags to a customer (additive) › Request Body

Add tags to a customer (additive) › Responses

Remove tags from a customer

Remove tags from a customer › path Parameters

Remove tags from a customer › query Parameters

Remove tags from a customer › Headers

Remove tags from a customer › Responses

Add tags to a invoice (additive)

Add tags to a invoice (additive) › path Parameters

Add tags to a invoice (additive) › Headers

Add tags to a invoice (additive) › Request Body

Add tags to a invoice (additive) › Responses

Remove tags from a invoice

Remove tags from a invoice › path Parameters

Remove tags from a invoice › query Parameters

Remove tags from a invoice › Headers

Remove tags from a invoice › Responses

Add tags to a plan (additive)

Add tags to a plan (additive) › path Parameters

Add tags to a plan (additive) › Headers

Add tags to a plan (additive) › Request Body

Add tags to a plan (additive) › Responses

Remove tags from a plan

Remove tags from a plan › path Parameters

Remove tags from a plan › query Parameters

Remove tags from a plan › Headers

Remove tags from a plan › Responses

Add tags to a product (additive)

Add tags to a product (additive) › path Parameters

Add tags to a product (additive) › Headers

Add tags to a product (additive) › Request Body

Add tags to a product (additive) › Responses

Remove tags from a product

Remove tags from a product › path Parameters

Remove tags from a product › query Parameters

Remove tags from a product › Headers

Remove tags from a product › Responses

Add tags to a subscription (additive)

Add tags to a subscription (additive) › path Parameters

Add tags to a subscription (additive) › Headers

Add tags to a subscription (additive) › Request Body

Add tags to a subscription (additive) › Responses

Remove tags from a subscription

Remove tags from a subscription › path Parameters

Remove tags from a subscription › query Parameters

Remove tags from a subscription › Headers

Remove tags from a subscription › Responses

List tags

List tags › query Parameters

List tags › Headers

List tags › Responses

Create a tag

Create a tag › Headers

Create a tag › Request Body

Create a tag › Responses

Get a tag

Get a tag › path Parameters

Get a tag › Headers

Get a tag › Responses

Soft-delete a tag

Soft-delete a tag › path Parameters

Soft-delete a tag › Headers

Soft-delete a tag › Responses

Update a tag

Update a tag › path Parameters

Update a tag › Headers