Admin

The Admin resource offers a set of endpoints such as the following:

AdminPayment Resource

Name Type Generated by Description
lastSuccessPaymentState string user Last payment state
currentPaymentStateName string user New payment state
transactionStatus string user New transaction status

Please refer Payment States information to understand the possible values of Payment State.

Please refer Payment Transaction Resource to understand the possible values of transactionStatus.

Administrative Apis

Miscellaneous administrative APIs

Trigger an invoice generation for all parked accounts

When the system detects an issue invoicing a customer Account, it will automatically PARK the Account as explained here. This API can be used after the issues have been resolved to remove accounts from the parked state and generate any outstanding invoices needed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/admin/invoices

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" \
    "http://127.0.0.1:8080/1.0/kb/admin/invoices"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

Long offset = 0L;
Long limit = 10L;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

adminApi.triggerInvoiceGenerationForParkedAccounts(offset, limit, NULL_PLUGIN_PROPERTIES, requestOptions);

ofset = 0
limit = 100
user = "demo"
reason = nil
comment = nil
plugin_properties = ["key%3Dvalue"]

KillBillClient::Model::Admin.trigger_invoice_generation_for_parked_accounts(ofset,
                                                                            limit,
                                                                            plugin_properties,
                                                                            user,
                                                                            reason,
                                                                            comment,
                                                                            options)

adminApi = killbill.api.AdminApi()

adminApi.trigger_invoice_generation_for_parked_accounts(created_by='demo',
                                                        reason='reason',
                                                        comment='comment')

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

api.triggerInvoiceGenerationForParkedAccounts('created_by');

$apiInstance = $client->getAdminApi();

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

$offset = 0;
$limit = 100;
$pluginProperty = array("pluginProperty_example");

$apiInstance->triggerInvoiceGenerationForParkedAccounts($xKillbillCreatedBy, $offset, $limit, $pluginProperty, $xKillbillReason, $xKillbillComment);

Example Response:

{
  "amount": 0,
  "currency": "USD",
  "status": "COMMITTED",
  "creditAdj": 0,
  "refundAdj": 0,
  "invoiceId": "5c7656b7-1974-447b-b263-1613448d4c1e",
  "invoiceDate": "2023-07-19",
  "targetDate": "2023-03-01",
  "invoiceNumber": "17700",
  "balance": 0,
  "accountId": "f65913b6-3185-48b2-b0cf-62495b879047",
  "bundleKeys": null,
  "credits": null,
  "items": [],
  "trackingIds": [],
  "isParentInvoice": false,
  "parentInvoiceId": null,
  "parentAccountId": null,
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
offset long no 0 starting offset for the page
limit long no 100 max results on this page
pluginProperty array of strings false omit list of plugin properties, if any

Returns

If successful, returns a status code of 200 and a list of invoices generated.

Update the state of a paymentTransaction and associated payment

Provides a way to fix the payment state data for a given Payment, if that data becomes corrupted. This could happen, for example, if a call to a third party payment gateway times out, leaving the system in an unknown state.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/admin/payments/{paymentId}/transactions/{paymentTransactionId}

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{
          "lastSuccessPaymentState" : "AUTH_FAILED",
          "currentPaymentStateName" : "AUTH_FAILED",
          "transactionStatus": "PAYMENT_FAILURE"         
        }' \
    "http://127.0.0.1:8080/1.0/kb/admin/payments/864c1418-e768-4cd5-a0db-67537144b685/transactions/864c1418-e768-4cd5-a0db-67537144b685"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

UUID paymentId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
UUID paymentTransactionId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");

String lastSuccessPaymentState = "AUTH_FAILED";
String currentPaymentStateName = "AUTH_FAILED";
String transactionStatus = "PAYMENT_FAILURE";

AdminPayment body = new AdminPayment(lastSuccessPaymentState,
                                     currentPaymentStateName,
                                     transactionStatus);

adminApi.updatePaymentTransactionState(paymentId,
                                       paymentTransactionId,
                                       body,
                                       requestOptions);

created_by = "demo"
reason = nil
comment = nil
payment_id = "6cb944a-b308-4488-b046-4b4d61d375a6"
transaction_id = "8gb944a-b308-4488-b046-4b4d61d375r3"
transaction_status = "PAYMENT_FAILURE"
payment_state_param = {
  "lastSuccessPaymentState" => "AUTH_FAILED",
  "currentPaymentStateName" => "AUTH_FAILED"
}
KillBillClient::Model::Admin.fix_transaction_state(payment_id,
                                                  transaction_id,
                                                  transaction_status,
                                                  payment_state_param,
                                                  created_by,
                                                  reason,
                                                  comment,
                                                  options_for_klient)

adminApi = killbill.api.AdminApi()

payment_id = '770d7802-9e03-45dc-a16a-dc58ddcb44d1'
payment_transaction_id = 'f20e1bca-8c3e-4a8f-b411-27f4362f858b'
body = AdminPayment(transaction_status='PAYMENT_FAILURE')

adminApi.update_payment_transaction_state(payment_id,
                                          payment_transaction_id,
                                          body,
                                          created_by='demo',
                                          reason='reason',
                                          comment='comment')

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

const paymentId = '770d7802-9e03-45dc-a16a-dc58ddcb44d1';
const paymentTransactionId = 'f20e1bca-8c3e-4a8f-b411-27f4362f858b';
const adminPayment: AdminPayment = {transactionStatus: "PAYMENT_FAILURE"};

api.updatePaymentTransactionState(adminPayment, paymentId, paymentTransactionId, 'created_by');

$apiInstance = $client->getAdminApi();

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

$body = new AdminPayment();
$body -> setTransactionStatus('PAYMENT_FAILURE');
$paymentId = "770d7802-9e03-45dc-a16a-dc58ddcb44d1";
$paymentTransactionId = "f20e1bca-8c3e-4a8f-b411-27f4362f858b";

$apiInstance->updatePaymentTransactionState($body, $xKillbillCreatedBy, $paymentId, $paymentTransactionId, $xKillbillReason, $xKillbillComment);

Request Body

An AdminPayment object containing, as a minimum, the new transactionStatus to be captured. The allowed values of the transactionStatus as well as what each transactionStatus means are already explained above.

Query Parameters

None.

Returns

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

Operational Apis

These APIs invalidate caches and move a host in and out of the rotation

Invalidate a specific cache, or invalidate all caches

Invalidates a specified cache. If no cache is specified, it invalidates all Kill Bill caches on the server. Note that this method only clears the local cache. In case of a multi-node implementation, this method would need to be invoked on each node.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/admin/cache

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    "http://127.0.0.1:8080/1.0/kb/admin/cache"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

String cacheName = "tenant";

adminApi.invalidatesCache(cacheName, requestOptions);

cache_name = nil
KillBillClient::Model::Admin.invalidates_cache(cache_name, options)

adminApi = killbill.api.AdminApi()

adminApi.invalidates_cache(cache_name='tenant')

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

api.invalidatesCache('tenant');

$apiInstance = $client->getAdminApi();

$cacheName = "tenant";

$apiInstance->invalidatesCache($cacheName);

Query Parameters

Name Type Required Default Description
cacheName string no all caches Cache name. Possible values are defined in the Cacheable interface

Returns

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

Invalidate Caches for an Account

Invalidates all Kill Bill caches on the server associated with a specific Account

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/admin/cache/accounts/{accountId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    "http://127.0.0.1:8080/1.0/kb/admin/cache/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");

adminApi.invalidatesCacheByAccount(accountId, requestOptions);

account_id = "2ad52f53-85ae-408a-9879-32a7e59dd03d"
KillBillClient::Model::Admin.invalidates_cache_by_account(account_id, options)

adminApi = killbill.api.AdminApi()

account_id = '2ad52f53-85ae-408a-9879-32a7e59dd03d'

adminApi.invalidates_cache_by_account(account_id)

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

const accountId = '7958908b-040a-4e2c-9606-4f1f62ac1c33';

api.invalidatesCacheByAccount(accountId);

$apiInstance = $client->getAdminApi();

$accountId = "7958908b-040a-4e2c-9606-4f1f62ac1c33";

$apiInstance->invalidatesCacheByAccount($accountId);

Query Parameters

None.

Response

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

Invalidate Caches for a Tenant

Invalidates all Kill Bill caches on the server associated with this Tenant

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/admin/cache/tenants

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    "http://127.0.0.1:8080/1.0/kb/admin/cache/tenants"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

adminApi.invalidatesCacheByTenant(requestOptions);

KillBillClient::Model::Admin.invalidates_cache_by_tenant(options)

adminApi = killbill.api.AdminApi()

adminApi.invalidates_cache_by_tenant()

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

api.invalidatesCacheByTenant();

$apiInstance = $client->getAdminApi();

$apiInstance->invalidatesCacheByTenant();

Query Parameters

None.

Returns

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

Put the host back into rotation

Adds a server back into the rotation after it has been removed.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/admin/healthcheck

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    "http://127.0.0.1:8080/1.0/kb/admin/healthcheck"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

adminApi.putInRotation(requestOptions);

KillBillClient::Model::Admin.put_in_rotation(options)

adminApi = killbill.api.AdminApi()

adminApi.put_in_rotation()

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

api.putInRotation();

$apiInstance = $client->getAdminApi();

$apiInstance->putInRotation();

Query Parameters

None.

Response

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

Remove a server from the rotation

Removes a server from the rotation during a deployment.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/admin/healthcheck

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    "http://localhost:8080/1.0/kb/admin/healthcheck"

import org.killbill.billing.client.api.gen.AdminApi;
protected AdminApi adminApi;

adminApi.putOutOfRotation(requestOptions);

KillBillClient::Model::Admin.put_out_of_rotation(options)

adminApi = killbill.api.AdminApi()

adminApi.put_out_of_rotation()

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

api.putOutOfRotation();

$apiInstance = $client->getAdminApi();

$apiInstance->putOutOfRotation();

Query Parameters

None.

Response

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

Low Level View Apis

This API group currently includes a single API to view entries in the system queues

Get queue entries

Returns low level details about queue entries. Results can be requested for a specific account or all accounts; for a specific queue or all queues, and for a specific service or all services. In addition, optional parameters may be specified, including history, for a specified date range; in processing; bus events; and notifications.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/admin/queues

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/octet-stream" \
    "http://localhost:8080/1.0/kb/admin/queues"

UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
String queueName = null;
String serviceName = null;
Boolean withHistory = true;
String minDate = null;
String maxDate = null;
Boolean withInProcessing = true;
Boolean withNotifications = true;
OutputStream outputStream = null;


adminApi.getQueueEntries(accountId,
                         queueName,
                         serviceName,
                         withHistory,
                         minDate,
                         maxDate,
                         withInProcessing,
                         withBusEvents,
                         withNotifications,
                         outputStream,
                         requestOptions);

account_id = "864c1418-e768-4cd5-a0db-67537144b685"
queue_name = ''
service_name = ''
with_history = true
min_date = ''
max_date = ''
with_in_processing = true
with_notifications = true
outputStream = ''
KillBillClient::Model::Admin.get_queues_entries(account_id,
                                                queue_name,
                                                service_name,
                                                with_history,
                                                min_date,
                                                max_date,
                                                with_in_processing,
                                                with_notifications,
                                                outputStream,
                                                options)

adminApi = killbill.api.AdminApi()

adminApi.get_queue_entries()

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

api.getQueueEntries();

$apiInstance = $client->getAdminApi();

$accountId = "38400000-8cf0-11bd-b23e-10b96e4ef00d";
$queueName = "queueName_example";
$serviceName = "serviceName_example";
$withHistory = true;
$minDate = "2023-01-01";
$maxDate = "2023-12-31";
$withInProcessing = true;
$withBusEvents = true;
$withNotifications = true;

$apiInstance->getQueueEntries($accountId, $queueName, $serviceName, $withHistory, $minDate, $maxDate, $withInProcessing, $withBusEvents, $withNotifications);

Example Response:

{
  "busEvents":[],
  "notifications":[]
}

Query Parameters

Name Type Required Default Description
accountId string no all accounts account id
queueName string no all queues queue name
serviceName string no all services service name
withHistory boolean no true if true include history
minDate string no from the beginning earliest date for history
maxDate string no current date latest date for history
withInProcessing boolean no true if true include in processing
withBusEvents boolean no true if true include bus events
withNotifications boolean no true if true include notifications

Notes: * If accountId is specified, minDate and maxDate have no effect and all the queue entries for the specified account are returned. * If withHistory is false, the minDate parameter has no effect and all queue entries up to the specified maxDate are returned. * If withHistory is true, the maxDate parameter has no effect and all queue entries starting from minDate are returned.

Returns

If successful, returns a status code of 200 and a list of queue entries of the specified types.