---
title: "Create a tag definition"
method: POST
path: "/1.0/kb/tagDefinitions"
tags: ["TagDefinition"]
---

# Create a tag definition

`POST /1.0/kb/tagDefinitions`

## Headers

- `X-Killbill-CreatedBy` string, required
- `X-Killbill-Reason` string
- `X-Killbill-Comment` string

## Request body

- TagDefinition
  - `id` string, uuid
  - `isControlTag` boolean
  - `name` string, required
  - `description` string, required
  - `applicableObjectTypes` string[]
  - `auditLogs` AuditLog[]
    - `changeType` string
    - `changeDate` string, date-time
    - `objectType` 'ACCOUNT' | 'ACCOUNT_EMAIL' | 'BLOCKING_STATES' | 'BUNDLE' | 'CUSTOM_FIELD' | 'INVOICE' | 'PAYMENT' | 'TRANSACTION' | 'INVOICE_ITEM' | 'INVOICE_PAYMENT' | 'SUBSCRIPTION' | 'SUBSCRIPTION_EVENT' | 'SERVICE_BROADCAST' | 'PAYMENT_ATTEMPT' | 'PAYMENT_METHOD' | 'TAG' | 'TAG_DEFINITION' | 'TENANT' | 'TENANT_KVS'
    - `objectId` string, uuid
    - `changedBy` string
    - `reasonCode` string
    - `comments` string
    - `userToken` string
    - `history` Entity
      - `id` string, uuid
      - `updatedDate` string, date-time
      - `createdDate` string, date-time

## Response `201`

Tag definition created successfully

- TagDefinition
  - `id` string, uuid
  - `isControlTag` boolean
  - `name` string, required
  - `description` string, required
  - `applicableObjectTypes` string[]
  - `auditLogs` AuditLog[]
    - `changeType` string
    - `changeDate` string, date-time
    - `objectType` 'ACCOUNT' | 'ACCOUNT_EMAIL' | 'BLOCKING_STATES' | 'BUNDLE' | 'CUSTOM_FIELD' | 'INVOICE' | 'PAYMENT' | 'TRANSACTION' | 'INVOICE_ITEM' | 'INVOICE_PAYMENT' | 'SUBSCRIPTION' | 'SUBSCRIPTION_EVENT' | 'SERVICE_BROADCAST' | 'PAYMENT_ATTEMPT' | 'PAYMENT_METHOD' | 'TAG' | 'TAG_DEFINITION' | 'TENANT' | 'TENANT_KVS'
    - `objectId` string, uuid
    - `changedBy` string
    - `reasonCode` string
    - `comments` string
    - `userToken` string
    - `history` Entity
      - `id` string, uuid
      - `updatedDate` string, date-time
      - `createdDate` string, date-time

## Other responses

- `400` — Invalid name or description supplied

---

[API](https://skmtc.dev/killbill/apis/kill-bill.md) · [All operations](https://skmtc.dev/killbill/apis/kill-bill/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/killbill/kill-bill/revisions/0fb95d23caf5/schema)