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.

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"
    }
  }
]