Custom Field

A custom field is an attribute (key-value pair) that may be attached to almost any resource.

This section provides APIs to list all custom fields, search for a specific custom field, and retrieve custom field audit logs. Searching may be based on the custom field id or on its name, value, or resource type. In addition, each resource provides APIs for the applicable CRUD operations: creation, retrieval, updating, and deletion.

Custom Field Resource

The Custom Field resource is associated with a key-value pair and has the following attributes:

Name	Type	Generated by	Description
customFieldId	string	system	UUID for this custom field
objectType	string	user	Type of the object this tag is attached to (e.g. "ACCOUNT")
objectID	string	system	UUID for the object
name	string	user	name of the custom field
value	string	user	value of the custom field
auditLogs	array	system	array of audit log records for this custom field

List all custom fields

Retrieves a list of all custom fields (name and value) with their associated resources and optional audit logs

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customFields/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"	"NONE", "MINIMAL", or "FULL"

Returns

Returns a list of records for all custom fields

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/customFields/pagination"

import org.killbill.billing.client.model.CustomFields;

protected CustomFieldApi customFieldApi;

Long offset = 0L;
Long limit = 100L;

CustomFields customFields = customFieldApi.getCustomFields(offset, 
                                                           limit, 
                                                           AuditLevel.FULL, 
                                                           requestOptions);

offset = 0
limit = 100
audit = 'NONE'

customField = KillBillClient::Model::CustomField

customFields = customField.find_in_batches(offset,
                                           limit,
                                           audit,
                                           options)

customFieldApi = killbill.CustomFieldApi()

customFields = customFieldApi.get_custom_fields()

const customFieldApi: killbill.CustomFieldApi = new killbill.CustomFieldApi(config);

const customFields: AxiosResponse<killbill.CustomField[], any> = await customFieldApi.getCustomFields();

$apiInstance = $client->getCustomFieldApi();

$customFields = $apiInstance->getCustomFields();

Example Response:

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Search custom fields

Searches for custom fields by specified search string. The search string is compared to the following attributes: customFieldId, objectId, objectType, name, and value. The operation returns the custom field records in which the search string matches all or part of any one of the attributes objectId, objectType, name, value. However, the string must match the entire attribute in case of customFieldId.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customField/search/{searchKey}

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"	"NONE", "MINIMAL", or "FULL"

Returns

Returns the records for matching custom fields, if any.

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/customFields/search/ACCOUNT"

import org.killbill.billing.client.model.CustomFields;

protected CustomFieldApi customFieldApi;

Long offset = 0L;
Long limit = 100L;
String searchKey = "ACCOUNT";

CustomFields customFields = customFieldApi.searchCustomFields(searchKey, 
                                                              offset, 
                                                              limit, 
                                                              AuditLevel.FULL,
                                                              requestOptions);

offset = 0
limit = 100

customFieldsApi = KillBillClient::Model::CustomField

searchKey = 'ACCOUNT'

customFields = customFieldsApi.find_in_batches_by_search_key(searchKey,
                                                             offset,
                                                             limit,
                                                             options);

customFieldApi = killbill.CustomFieldApi()

searchKey = 'ACCOUNT'

customFields = customFieldApi.search_custom_fields(searchKey);

const customFieldApi: killbill.CustomFieldApi = new killbill.CustomFieldApi(config);

const searchKey = 'ACCOUNT';

const customFields: AxiosResponse<killbill.CustomField[], any> = await customFieldApi.searchCustomFields(searchKey);

$apiInstance = $client->getCustomFieldApi();

$searchKey = 'ACCOUNT';

$customFields = $apiInstance->searchCustomFields($searchKey);

Example Response:

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Search custom fields by resource type, name, and optional value

Searches for a specific custom field by its resource type, name, and optional value

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customField/search

Query Parameters

Name	Type	Required	Default	Description
objectType	string	true	none	type of resource to search (e.g., "ACCOUNT")
fieldName	string	true	none	name of the custom field to search for
fieldValue	string	false	any value	value of the custom field to search for
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns the record for the specified custom field, if it exists

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/customFields/search?objectType=ACCOUNT&fieldName=importance"

import org.killbill.billing.client.model.CustomFields;

protected CustomFieldApi customFieldApi;

String objectType = "ACCOUNT";
String fieldName = "customFieldName";
String fieldValue = "customFieldValue";

CustomFields customFields = customFieldApi.searchCustomFieldsByTypeName(objectType, 
                                                                        fieldName, 
                                                                        fieldValue,
                                                                        requestOptions);

offset = 0
limit = 100

customFields = KillBillClient::Model::CustomField

objectType = 'ACCOUNT';
fieldName = 'customFieldName';
fieldValue = 'customFieldValue';

customField = customFields.find_in_batches_by_search_type_name(objectType,
                                                               fieldName,
                                                               fieldValue,
                                                               offset,
                                                               limit,
                                                               options)

customFieldApi = killbill.CustomFieldApi()

objectType = 'ACCOUNT';
fieldName = 'customFieldName';

customFields = customFieldApi.search_custom_fields_by_type_name(object_type=objectType,
                                                                field_name=fieldName);

const customFieldApi: killbill.CustomFieldApi = new killbill.CustomFieldApi(config);

const objectType = 'ACCOUNT';
const fieldName = 'customFieldName';

const customField: AxiosResponse<killbill.CustomField[], any> = await customFieldApi.searchCustomFieldsByTypeName(objectType, fieldName);

$apiInstance = $client->getCustomFieldApi();

$objectType = 'ACCOUNT';
$fieldName = 'customFieldName';
$fieldValue = 'customFieldValue';

$customFields = $apiInstance->searchCustomFieldsByTypeName($objectType,
                                                           $fieldName,
                                                           $fieldValue);

Example Response:

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Audit Logs

Retrieve custom field audit logs with history by custom field id

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customFields/{customFieldId}/auditLogsWithHistory

Example Request:

    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/customFields/4b498210-b177-4aae-a539-cf594adaa221/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.CustomFieldApi;

protected CustomFieldApi customFieldApi;

UUID customFieldId = UUID.fromString("d7c2ed2e-9fcf-491c-9844-2d9e5efbfc4b");

AuditLogs auditLogsWithHistory = customFieldApi.getCustomFieldAuditLogsWithHistory(customFieldId,
                                                                                   requestOptions);

customFields = KillBillClient::Model::CustomField.new

customFields.custom_field_id = 'd7c2ed2e-9fcf-491c-9844-2d9e5efbfc4b'

auditLogsWithHistory = customFields.audit_logs_with_history(options)

customFieldApi = killbill.CustomFieldApi()

customFieldId = 'd7c2ed2e-9fcf-491c-9844-2d9e5efbfc4b'

customFieldAuditLogs = customFieldApi.get_custom_field_audit_logs_with_history(customFieldId)

const customFieldApi: killbill.CustomFieldApi = new killbill.CustomFieldApi(config);

const customFieldId = 'd7c2ed2e-9fcf-491c-9844-2d9e5efbfc4b';

const customFieldAuditLogs: AxiosResponse<killbill.AuditLog[], any> = await customFieldApi.getCustomFieldAuditLogsWithHistory(customFieldId);

$apiInstance = $client->getCustomFieldApi();

$customFieldId = 'd7c2ed2e-9fcf-491c-9844-2d9e5efbfc4b';

$customFieldAuditLogsWithHistory = $apiInstance->getCustomFieldAuditLogsWithHistory($customFieldId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2013-08-01T06:00:00.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "2b3920ae-6b8c-4deb-9ed9-132ff632e692",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:00.000Z",
      "updatedDate": "2013-08-01T06:00:00.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2013-08-01T06:00:01.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "6343d19f-cef0-486a-8114-85c7573639a0",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:01.000Z",
      "updatedDate": "2013-08-01T06:00:01.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "another_test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  },
  {
    "changeType": "DELETE",
    "changeDate": "2013-08-01T06:00:01.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "9a9343bd-9cba-417b-be17-713ff456b5f7",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:01.000Z",
      "updatedDate": "2013-08-01T06:00:01.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "another_test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  }
]

Query Parameters

None.

Returns

Returns a list of custom field logs with history.