Tags

Endpointhttps://api.kontier.eu/v1

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

GET

https://api.kontier.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 stays outside the grammar as a control flag (see its parameter description).

Required scope: tag.read (Read tags).

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

limit

integer · min: 1

Page size (default 50, max 200)

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.

sort

string

Ordering: created_at, name, entity_type, description or color, each with an optional :asc/:desc suffix (default created_at:desc). Tags with no description or no color sort last in both directions. entity_type orders the stored code, not its translated label. An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page. usage_count is not orderable: it is a per-row count over taggings, not a column of tags.

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.

array | null · required

object · required

GET/tags

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

shell

Example Responses

{
  "data": [
    {
      "archived_at": "2024-08-25T15:00:00Z",
      "color": "#1A2B3C",
      "created_at": "2024-08-25T15:00:00Z",
      "deleted_at": "2024-08-25T15:00:00Z",
      "description": "Customers on an enterprise contract.",
      "entity_type": "CUSTOMER",
      "id": "07d536e2-51cf-5d4d-aaa1-4af54c14dec1",
      "name": "enterprise",
      "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
      "status": "active",
      "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.kontier.eu/v1

/tags

Creates a new tag scoped to the calling organization.

Required scope: tag.write (Manage tags).

Create a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

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

entity_type

string · enum · required

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 · required

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

color

string

Optional display color as a #RRGGBB hex string.

description

string · maxLength: 500

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

Create a tag › Responses

Created

object · required

POST/tags

curl --request POST \
  --url https://api.kontier.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": "#1A2B3C",
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "Customers on an enterprise contract.",
    "entity_type": "CUSTOMER",
    "id": "07d536e2-51cf-5d4d-aaa1-4af54c14dec1",
    "name": "enterprise",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "status": "active",
    "updated_at": "2024-08-25T15:00:00Z",
    "usage_count": 0
  }
}

json

application/json

Get a tag

GET

https://api.kontier.eu/v1

/tags/{id}

Returns a single tag by UUID.

Required scope: tag.read (Read tags).

Get a tag › path Parameters

id

string · uuid · required

Tag UUID

Get a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

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.kontier.eu/v1

/tags/{id}

Marks the tag deleted and cascades to drop all taggings that referenced it. Fails with 409 TAG_REFERENCED while a live audience targets the tag in a rule (promotions target tags only through an audience); the error names the audiences, and the tag can be deleted once it is removed from their rules.

Required scope: tag.write (Manage tags).

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.kontier.eu/v1

/tags/{id}

Applies partial updates to a tag. status: archived archives the tag and status: active restores it. Setting description or color to null clears it; an empty string is refused.

Required scope: tag.write (Manage tags).

Update a tag › path Parameters

id

string · uuid · required

Tag UUID

Update a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

Update a tag › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a tag › Request Body

color

string | null · minLength: 1

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

description

string | null · minLength: 1 · maxLength: 500

New description; null clears it; omitted leaves it unchanged.

name

string · maxLength: 100

New display name; omitted leaves it unchanged.

status

string · enum

archived hides the tag from pickers; active restores it. Omitted leaves it unchanged.

Enum values:

active

archived

Update a tag › Responses

object · required

PATCH/tags/{id}

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

shell

Example Request Body

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

json

Example Responses

{
  "data": {
    "archived_at": "2024-08-25T15:00:00Z",
    "color": "#1A2B3C",
    "created_at": "2024-08-25T15:00:00Z",
    "deleted_at": "2024-08-25T15:00:00Z",
    "description": "Customers on an enterprise contract.",
    "entity_type": "CUSTOMER",
    "id": "07d536e2-51cf-5d4d-aaa1-4af54c14dec1",
    "name": "enterprise",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "status": "active",
    "updated_at": "2024-08-25T15:00:00Z",
    "usage_count": 0
  }
}

json

application/json

FX Accounting

List tags

GET

https://api.kontier.eu/v1

/tags

Required scope: tag.read (Read tags).

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

limit

integer · min: 1

Page size (default 50, max 200)

Example: 50

cursor

string

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.

sort

string

X-Workspace-Id

string

Workspace UUID or slug.

array | null · required

object · required

Create a tag

POST

https://api.kontier.eu/v1

/tags

Creates a new tag scoped to the calling organization.

Required scope: tag.write (Manage tags).

Create a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

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

entity_type

string · enum · required

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 · required

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

color

string

Optional display color as a #RRGGBB hex string.

description

string · maxLength: 500

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

Create a tag › Responses

Created

object · required

Get a tag

GET

https://api.kontier.eu/v1

/tags/{id}

Returns a single tag by UUID.

Required scope: tag.read (Read tags).

Get a tag › path Parameters

id

string · uuid · required

Tag UUID

Get a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

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.kontier.eu/v1

/tags/{id}

Required scope: tag.write (Manage tags).

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.kontier.eu/v1

/tags/{id}

Applies partial updates to a tag. status: archived archives the tag and status: active restores it. Setting description or color to null clears it; an empty string is refused.

Required scope: tag.write (Manage tags).

Update a tag › path Parameters

id

string · uuid · required

Tag UUID

Update a tag › query Parameters

include

string[] · explode: true

Extra data to add to the response: usage_count. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.

Enum values:

usage_count

Update a tag › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a tag › Request Body

color

string | null · minLength: 1

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

description

string | null · minLength: 1 · maxLength: 500

New description; null clears it; omitted leaves it unchanged.

name

string · maxLength: 100

New display name; omitted leaves it unchanged.

status

string · enum

archived hides the tag from pickers; active restores it. Omitted leaves it unchanged.

Enum values:

active

archived

Update a tag › Responses

object · required

Tags

List tags

List tags › query Parameters

List tags › Headers

List tags › Responses

Create a tag

Create a tag › query Parameters

Create a tag › Headers

Create a tag › Request Body

Create a tag › Responses

Get a tag

Get a tag › path Parameters

Get a tag › query 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 › query Parameters

Update a tag › Headers

Update a tag › Request Body

Update a tag › Responses

Tags

List tags

List tags › query Parameters

List tags › Headers

List tags › Responses

Create a tag

Create a tag › query Parameters

Create a tag › Headers

Create a tag › Request Body

Create a tag › Responses

Get a tag

Get a tag › path Parameters

Get a tag › query 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 › query Parameters

Update a tag › Headers

Update a tag › Request Body

Update a tag › Responses