Tag

A tag is a label that may be attached to almost any resource. While custom fields allow you to attach {key, value} pairs to various objects in the system, single values can also be attached to various objects in the system by using tags. There are two categories of tags: System Tags and User Tags.

System Tags: These are interpreted by the system to change its behavior. Certain tags can only be attached to specific resource types -- e.g Account. In order to distinguish them from the user tags, the system tags are uppercase symbols.
User Tags: These are defined by the user for any desired purpose and are not interpreted by the system and can be anything as long as it a lowercase symbol. For example, good_customer could be a tag that can be attached to a customer Account. User Tags must be defined using the Tag Definition APIs. These tags may be attached to almost any resource type.

Kill Bill provides a small set of predefined System Tags that affect the behavior of the system. For example, AUTO_PAY_OFF prevents the system from initiating automatic payment of an invoice. System Tags may be attached only to specific resource types, and most (including AUTO_PAY_OFF) apply only to Accounts.

The following system tags have been defined:

Tag	tagDefinitionId	Applicable Object types	Description
`AUTO_PAY_OFF`	`00000000-0000-0000-0000-000000000001`	`ACCOUNT`	Suspends payments until removed.
`AUTO_INVOICING_OFF`	`00000000-0000-0000-0000-000000000002`	`ACCOUNT`	Suspends invoicing until removed.
`OVERDUE_ENFORCEMENT_OFF`	`00000000-0000-0000-0000-000000000003`	`ACCOUNT`	Suspends overdue enforcement behaviour until removed.
`WRITTEN_OFF`	`00000000-0000-0000-0000-000000000004`	`INVOICE`	Indicates that an invoice is written off. This has no effect on billing or payment.
`MANUAL_PAY`	`00000000-0000-0000-0000-000000000005`	`ACCOUNT`	Indicates that Killbill doesn't process payments for this account. That is, the account uses external payments only.
`TEST`	`00000000-0000-0000-0000-000000000006`	`ACCOUNT`	Indicates that this is a test account.
`PARTNER`	`00000000-0000-0000-0000-000000000007`	`ACCOUNT`	Indicates that this is a partner account.
`AUTO_INVOICING_DRAFT`	`00000000-0000-0000-0000-000000000008`	`ACCOUNT`	Generate account invoices in DRAFT mode.
`AUTO_INVOICING_REUSE_DRAFT`	`00000000-0000-0000-0000-000000000009`	`ACCOUNT`	Use existing draft invoice if exists.

This section provides APIs to list all tags, search for a specific tag, and retrieve tag audit logs. In addition, each resource provides APIs for the applicable CRUD operations: create, read, update and delete.

Tag Resource

A tag resource represents a tag. It has the following attributes:

Name	Type	Generated by	Description
tagId	string	system	UUID for this specific tag
objectType	string	user	Type of the object this tag is attached to (e.g. "ACCOUNT")
objectID	string	system	UUID for the object
tagDefinitionId	string	system	UUID for the tag definition
tagDefinitionName	string	user	name for the tag definition
auditLogs	array	system	array of audit log records for this tag

List all tags

Retrieves a list of all tags with their associated resources and tag definitions

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tags/pagination

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Returns

If successful, returns a status code of 200 and a list of tag resource objects.

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/tags/pagination"

import org.killbill.billing.client.api.gen.TagApi;
protected TagApi tagApi;

List<Tag> tags = tagApi.getTags(requestOptions);

offset = 0
limit = 100

tags = KillBillClient::Model::Tag.find_in_batches(offset, limit, options)

tagApi = killbill.api.TagApi()

tags = tagApi.get_tags()

const api: killbill.TagApi = new killbill.TagApi(config);

const response: AxiosResponse<killbill.Tag[], any> = await api.getTags();

$apiInstance = $client->getTagApi();

$offset = 0;
$limit = 100;
$audit = "NONE";

$result = $apiInstance->getTags($offset, $limit, $audit);

Example Response:

[
  {
    "tagId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "tagDefinitionId": "1ac0218e-0d2b-4c65-841f-cff8af92a100",
    "tagDefinitionName": "sleepy",
    "auditLogs": []
  }
]

Search tags

Searches for a specific tag. The search string is compared to the following attributes: tagId, objectType, tagDefinitionName.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tags/search/{tagId}

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Returns

If successful, returns a status code of 200 and a list of tag resource objects that contain a match for the specified search key.

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/tags/search/13fe6f2c-91af-4635-aa9c-52e04d99b5ec"

import org.killbill.billing.client.api.gen.TagApi;
protected TagApi tagApi;

String searchKey = "WRITTEN_OFF";
List<Tag> tags = tagApi.searchTags(searchKey, requestOptions);

search_key="ACCOUNT"
offset = 0
limit = 100

tags = KillBillClient::Model::Tag.find_in_batches_by_search_key(search_key, offset, limit, options)

tagApi = killbill.api.TagApi()

search_key = "5ad7519f-3698-4c75-8d93-98c7a465010e"
tags = tagApi.search_tags(search_key)

const api: killbill.TagApi = new killbill.TagApi(config);

const searchKey = '__PARK__';

const response: AxiosResponse<killbill.Tag[], any> = await api.searchTags(searchKey);

$apiInstance = $client->getTagApi();

$searchKey = "ad9cf851-1076-49cc-9b98-4f1612f9dbe4";
$offset = 0;
$limit = 100;
$audit = "NONE";

$result = $apiInstance->searchTags($searchKey, $offset, $limit, $audit);

Example Response:

[
  {
    "tagId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "tagDefinitionId": "1ac0218e-0d2b-4c65-841f-cff8af92a100",
    "tagDefinitionName": "sleepy",
    "auditLogs": []
  }
]

Retrieve tag audit logs

Retrieve a list of audit log records showing changes to the tag. History information (a copy of the full tag object) is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tags/{tagId}/auditLogsWithHistory

Query Parameters

None.

Returns

If successful, returns a status code of 200 and a list of audit log objects.

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/tags/26e22dbf7-a493-4402-b1e3-4bec54c39f31/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.TagApi;
protected TagApi tagApi;

UUID tagId = UUID.fromString("720f92c3-a6aa-473b-bc3d-a885f21b5401");
AuditLogs logs = tagApi.getTagAuditLogsWithHistory(tagId,requestOptions);

tag = KillBillClient::Model::Tag.new
tag.tag_id = "7e7f6af6-a844-4ce0-b7d1-f258290d8ad4"

audit_logs = tag.audit_logs_with_history(options)
puts "logs #{audit_logs}"

tagApi = killbill.api.TagApi()

tag_id = "5ad7519f-3698-4c75-8d93-98c7a465010e"

audit_logs = tagApi.get_tag_audit_logs_with_history(tag_id)

const api: killbill.TagApi = new killbill.TagApi(config);

const tagId = '4c484114-07cd-4f81-9558-f57ada4858f6';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getTagAuditLogsWithHistory(tagId);

$apiInstance = $client->getTagApi();

$tagId = "ad9cf851-1076-49cc-9b98-4f1612f9dbe4";

$result = $apiInstance->getTagAuditLogsWithHistory($tagId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2013-09-01T06:00:05.000Z",
    "objectType": "TAG",
    "objectId": "6e22dbf7-a493-4402-b1e3-4bec54c39f31",
    "changedBy": "test_fixed_and_recurrring_items",
    "reasonCode": null,
    "comments": "Closing account",
    "userToken": "06d4fa80-f6ab-4760-aa97-2cd4ab83fd37",
    "history": {
      "id": null,
      "createdDate": "2013-09-01T06:00:05.000Z",
      "updatedDate": "2013-09-01T06:00:05.000Z",
      "recordId": 1,
      "accountRecordId": 11,
      "tenantRecordId": 2,
      "tagDefinitionId": "00000000-0000-0000-0000-000000000002",
      "objectId": "037a6b81-f351-4e09-b2ea-f76f2fb0189e",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "TAG",
      "historyTableName": "TAG_HISTORY"
    }
  }
]