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

customField = KillBillClient::Model::CustomField

customFields = customField.find_in_batches(offset,
                                           limit,
                                           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.