Tag Definition

These APIs manage a tag definition resource object, which provides the definition for a user-defined tag.

Tag Definition Resource

Each tag is associated with a specific tag definition. A tag definition is a schema or template, and a tag is an instance of it. Please refer to the Tags section for an overview of tags. Kill Bill provides a small set of predefined System Tags. Users may define their own tags; however, when using User Tags, one must first create the associated tag definition.

The tag definition resource includes the following attributes:

Name	Type	Generated by	Description
id	string	system	UUID for the tag definition
isControlTag	boolean	system	True if this is a control tag
name	string	user	Name of the tag definition
description	string	user	Description of the tag definition
applicableObjectTypes	list	user	see below
auditLogs	array	system	array of audit log records for this tag definition

applicableObjectTypes: A list of Strings giving the name(s) of resource types that can be given this tag. See ObjectType for a list of the possible values.

Tag Definition

The APIs in this group provide the ability to create, retrieve, and delete tag definitions.

Create a tag definition

Creates a new tag definition.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/tagDefinitions

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "name": "good_customer", "description": "a good customer", "applicableObjectTypes": ["ACCOUNT"]}' \
    "http://127.0.0.1:8080/1.0/kb/tagDefinitions"

import org.killbill.billing.client.api.gen.TagDefinitionApi;
protected TagDefinitionApi tagDefinitionApi;

final boolean isControlTag = false;
final String tagName = "tag_name";
final String tagDescription = "tag description";
List<ObjectType> applicableObjectTypes = List.of(ObjectType.BUNDLE, ObjectType.SUBSCRIPTION);
final List<AuditLog> EMPTY_AUDIT_LOGS = Collections.emptyList();

TagDefinition tagDefinition = new TagDefinition(null, isControlTag, tagName, tagDescription, applicableObjectTypes, EMPTY_AUDIT_LOGS);
TagDefinition createdTagDefinition = tagDefinitionApi.createTagDefinition(tagDefinition, requestOptions);

user = "demo"
reason = nil
comment = nil

tagDefinition = KillBillClient::Model::TagDefinition.new
tagDefinition.name = "tag_name"
tagDefinition.description = "tag description"
tagDefinition.applicable_object_types = ['BUNDLE', 'SUBSCRIPTION']
tagDefinition.is_control_tag = false

tagDefinition.create(user,
                    reason,
                    comment,
                    options)

tagDefinitionApi = killbill.api.TagDefinitionApi()

tagDefinition = TagDefinition(name='tag_name', description='tag description', applicable_object_types=['BUNDLE', 'SUBSCRIPTION','ACCOUNT'], is_control_tag=False)

tagDefinitionApi.create_tag_definition(tagDefinition,
                                       created_by='demo',
                                       reason='reason',
                                       comment='comment')

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

const applicableObjectTypes = ['INVOICE', 'TENANT'];
const tagDefinition: TagDefinition = {name: "tag_name", description: "tag description", "isControlTag": false, "applicableObjectTypes":applicableObjectTypes};

api.createTagDefinition(tagDefinition, 'created_by');

$apiInstance = $client->getTagDefinitionApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$tagDefinition = new TagDefinition();
$tagDefinition -> setName("tag_name");
$tagDefinition -> setDescription("tag description");
$tagDefinition -> setIsControlTag(false);
$applicableObjectTypes = array("ACCOUNT","INVOICE");
$tagDefinition -> setApplicableObjectTypes($applicableObjectTypes);

$result = $apiInstance->createTagDefinition($tagDefinition, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment);

Request Body

A TagDefinition resource object with at least the following attributes: name, description, and applicableObjectTypes. The list of applicableObjectTypes may not be empty.

Query Parameters

none

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains the new tag definition id.

Lists all tag definitions (corresponding to both system and user tags) for this tenant.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tagDefinitions

Example Request:

curl -v \
    -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/tagDefinitions"

import org.killbill.billing.client.api.gen.TagDefinitionApi;
protected TagDefinitionApi tagDefinitionApi;

List<TagDefinition> tagDefinitions = tagDefinitionApi.getTagDefinitions(AuditLevel.NONE, requestOptions);

audit = 'NONE'

tag_definitions = KillBillClient::Model::TagDefinition.all(audit, options)

tagDefinitionApi = killbill.api.TagDefinitionApi()

tag_definitions = tagDefinitionApi.get_tag_definitions()

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

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

$apiInstance = $client->getTagDefinitionApi();

$audit = "NONE";

$result = $apiInstance->getTagDefinitions($audit);

Example Response:

{
    "id": "93f2bc59-e18d-4a5e-a645-9386c76fc03f",
    "isControlTag": false,
    "name": "good_customer",
    "description": "a good customer",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
},
{
    "id": "00000000-0000-0000-0000-000000000001",
    "isControlTag": true,
    "name": "AUTO_PAY_OFF",
    "description": "Suspends payments until removed.",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
}

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

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

Retrieve a tag definition by its ID

This API retrieves a tag definitions resource object based on its tag definition ID.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}

Example Request:

curl -v \
    -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/tagDefinitions/93f2bc59-e18d-4a5e-a645-9386c76fc03f"

import org.killbill.billing.client.api.gen.TagDefinitionApi;
protected TagDefinitionApi tagDefinitionApi;

UUID tagDefinitionId = UUID.fromString("ed9e5163-4674-4e24-9545-db7aa581f93c");
TagDefinition tagDefinition = tagDefinitionApi.getTagDefinition(tagDefinitionId, AuditLevel.NONE, requestOptions);

tag_definition_id = "30363fe5-310d-4446-b000-d7bb6e6662e2"
audit = 'NONE'

tag_definition = KillBillClient::Model::TagDefinition.find_by_id(tag_definition_id, audit, options)

tagDefinitionApi = killbill.api.TagDefinitionApi()

tag_definition_id = '3ba41ebd-71f0-4a27-981b-86c6054f58dd'

tag_definition = tagDefinitionApi.get_tag_definition(tag_definition_id)

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

const tagDefinitionId = 'f27312df-4e8f-43c8-97aa-47c2b65c4152';

const response: AxiosResponse<killbill.TagDefinition, any> = await api.getTagDefinition(tagDefinitionId);

$apiInstance = $client->getTagDefinitionApi();

$tagDefinitionId = "96f4933f-96b2-4268-a8ee-2d40734b6115";
$audit = "NONE";

$result = $apiInstance->getTagDefinition($tagDefinitionId, $audit);

Example Response:

{
    "id": "93f2bc59-e18d-4a5e-a645-9386c76fc03f",
    "isControlTag": false,
    "name": "good_customer",
    "description": "a good customer",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
}

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Returns

If successful, returns a status code of 200 and a tag definition resource object.

Delete a tag definition

Deletes a tag definition.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/tagDefinitions/93f2bc59-e18d-4a5e-a645-9386c76fc03f"

import org.killbill.billing.client.api.gen.TagDefinitionApi;
protected TagDefinitionApi tagDefinitionApi;

UUID tagDefinitionId = UUID.fromString("ed9e5163-4674-4e24-9545-db7aa581f93c");
tagDefinitionApi.deleteTagDefinition(tagDefinitionId, requestOptions);

user = "demo"
reason = nil
comment = nil

tagDefinition = KillBillClient::Model::TagDefinition.new
tagDefinition.id = "2b9d7197-f6a0-4d5f-a0ad-1e3c3e22a0ce"

tagDefinition.delete(user, reason, comment, options);

tagDefinitionApi = killbill.api.TagDefinitionApi()

tag_definition_id = '2a4b9f36-6a53-4553-a2ef-d0bddf8e831a'

tagDefinitionApi.delete_tag_definition(tag_definition_id,
                                       created_by='demo',
                                       reason='reason',
                                       comment='comment')

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

const tagDefinitionId = '96f4933f-96b2-4268-a8ee-2d40734b6115';

api.deleteTagDefinition(tagDefinitionId, 'created_by');

$apiInstance = $client->getTagDefinitionApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$tagDefinitionId = "3ba41ebd-71f0-4a27-981b-86c6054f58dd";

$apiInstance->deleteTagDefinition($tagDefinitionId, $xKillbillCreatedBy, $xKillbillReason, $xKillbillComment);

Query Parameters

None.

Response

If successful, returns a status code of 204 and an empty body.

Audit Logs

Audit logs provide a record of events that occur involving various specific resources. For details on audit logs see Audit and History.

Retrieve tag definition audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified tag definition. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}/auditLogsWithHistory

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/tagDefinitions/92991586-df8a-4d8d-9d55-61172c52fa45/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.TagDefinitionApi;
protected TagDefinitionApi tagDefinitionApi;

UUID tagDefinitionId = UUID.fromString("06d991f7-f06a-4e45-80d2-c3b44a97f8bc");
AuditLogs logs = tagDefinitionApi.getTagDefinitionAuditLogsWithHistory(tagDefinitionId, requestOptions);

tag_definition = KillBillClient::Model::TagDefinition.new
tag_definition.id = "2a4b9f36-6a53-4553-a2ef-d0bddf8e831a"

audit_logs = tag_definition.audit_logs_with_history(options)

tagDefinitionApi = killbill.api.TagDefinitionApi()

tag_definition_id = '3ba41ebd-71f0-4a27-981b-86c6054f58dd'

audit_logs = tagDefinitionApi.get_tag_definition_audit_logs_with_history(tag_definition_id)

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

const tagDefinitionId = 'f27312df-4e8f-43c8-97aa-47c2b65c4152';

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

$apiInstance = $client->getTagDefinitionApi();

$tagDefinitionId = "96f4933f-96b2-4268-a8ee-2d40734b6115";

$result = $apiInstance->getTagDefinitionAuditLogsWithHistory($tagDefinitionId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-26T01:56:48.000Z",
    "objectType": "TAG_DEFINITION",
    "objectId": "92991586-df8a-4d8d-9d55-61172c52fa45",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "039f01ea-460a-4edd-bfbc-39a68149cad2",
    "history": {
      "id": null,
      "createdDate": "2019-02-26T01:56:48.000Z",
      "updatedDate": "2019-02-26T01:56:48.000Z",
      "recordId": 1,
      "accountRecordId": 1,
      "tenantRecordId": 1,
      "name": "good_customer",
      "applicableObjectTypes": "ACCOUNT",
      "description": "a good customer",
      "isActive": true,
      "tableName": "TAG_DEFINITIONS",
      "historyTableName": "TAG_DEFINITION_HISTORY"
    }
  }
]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of tag definition audit logs with history.

Tag Definition

Tag Definition Resource

Tag Definition

Create a tag definition

List tag definitions

Retrieve a tag definition by its ID

Delete a tag definition

Audit Logs

Retrieve tag definition audit logs with history by id