Account

Each of your customers is identified by an account. The information for an account is contained in an account resource object. The endpoints in this group manage the account resource and the information it contains.

Account Resource

An Account resource represents a customer. This is the top level per-customer resource. All other per-customer data, such as bundles, subscriptions, invoices and payments, will be linked to this resource. An account resource may contain Personally Identifiable Information (PII) for the customer such as name, address, email, etc. A large number of endpoints are available to manage not only purely account related information -- e.g name -- but other per-account data as well.

The attributes contained in the account resource are the following:

Name Type Generated by Description
accountId string system UUID for this account
externalKey string user Optional external key provided by the client
referenceTime string system ISO date and time this account was created
parentAccountId string user UUID for the parent account, if any, if the hierarchical accounts (HA) model is used
isPaymentDelegatedToParent boolean user For the hierarchical model, indicates whether the parent account, if any, is handling payments for this account
currency string user Default currency for the customer
billCycleDayLocal integer system or user Default day of the month to bill customers for subscriptions with an ACCOUNT billing alignment and a billing period that is a multiple of one month.
paymentMethodId string user UUID for the default payment method used by the system to make recurring payments
name string user Name of the account
firstNameLength integer user Length of the first name (first part of name)
company string user Customer's company name
address1 string user Address line 1
address2 string user Address line 2
city string user Customer's city
state string user Customer's state, if any
postalCode string user Customer's postal code, if any
country string user Customer's ISO country identifier
locale string user ISO locale code for customer language
timeZone string user Descriptor for the customer's time zone. Used by the system to make any required transformation from DateTime to LocalDate
phone string user Phone contact number to reach the customer
email string user Primary email to reach the customer
notes string user Additonal notes about the customer, usually set by the customer service department
isMigrated boolean user Indicates whether this account has been migrated from another system
accountCBA integer system Account credit, if any
accountBalance integer system Account balance, if any
auditLogs array system Array of audit log records for this account

The name is usually the personal name of the account owner. We recommend that this be entered so that the first word is an acceptable short form for the complete name, such as "first name" in most English-speaking cultures. In this case the value firstNameLength enables your code to extract this part of the name for informal greetings. For information on name formats in various countries see Personal Names around the World by the W3C.

A list of valid timeZone strings is given at timezone strings.

For information about migrating accounts from a previous system see the Migration Guide.

Accounts

Create an Account

Create a new customer Account.

HTTP Request

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

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": "John Doe", "email": "john@laposte.com", "currency": "USD"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts" 
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

Account body = new Account();
body.setName("John Doe");
body.setEmail("john@laposte.com");
body.setCurrency(Currency.USD);

Account result = accountApi.createAccount(body, requestOptions);
account = KillBillClient::Model::Account.new

user = 'user'
reason = 'reason'
comment = 'comment'

account.name = "John Doe"
account.email = "john@laposte.com"
account.currency = "USD"

account.create(user, reason, comment, options)
accountApi = killbill.AccountApi()

body = Account(name='John Doe', 
               email='john@laposte.com', 
               currency='USD')

accountApi.create_account(body,
                          created_by='demo',
                          reason='reason', 
                          comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.Account = {name: 'John Doe',email: 'john1@laposte.com',currency: 'USD'};

api.createAccount(body,'created_by');
$apiInstance = $client->getAccountApi();

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

$account = new Account();

$account->setName('TestPHPAccount');
$account->setEmail('TestPHPAccount@email.com');
$account->setCurrency('USD');

$apiInstance->createAccount($account,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Request Body

The body of the request is a JSON string specifying any attributes of the resource that need to be assigned an initial value. No attributes are required. For any attributes omitted, the following defaults are generated:

Attribute Default
accountId System generated UUID
externalKey Copy of accountId
billCycleDayLocal 0
isPaymentDelegatedToParent false
referenceTime ISO time-date code for the current time in the specified timezone
timeZone "UTC"
all others null

All attributes are optional, so it is possible to quickly create a shell account. This account could be used for test purposes, so its attributes can be filled in later. This also ensures the initial account contains no PII. Note, however, that the currency attribute must have a non-null value. This cannot be added later and is required for invoicing to work properly.

A few fields are not updatable; they can only be set once when creating the original Account. These include externalKey, currency, timeZone, and referenceTime. In addition the billCycleDayLocal can be updated but only once, that is one can create an Account without specifying the billCycleDayLocal and later update its value; this, in particular allows the system to update its value to a good default, that is one that will avoid leading prorations, when creating the first subscription.

The accountId and audit logs are generated by the system and cannot be set or modified by the user.

In order to create an account as a child account, the parentAccountId attribute needs to be specified with the id of the parent account. Also, the isPaymentDelegatedToParent attribute can be specified with a true/false value. A false indicates that the child account will be responsible for paying its own invoices while a true indicates that the parent account will be responsible for paying the child account invoices.

Query Parameters

none

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the account object, including the generated accountId.

Retrieve an Account by its ID

Retrieves the full resource object for an Account using its accountId.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}

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/accounts/36c05a84-563b-4794-8958-772d93e677e1" 
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("36c05a84-563b-4794-8958-772d93e677e1");
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info

Account result = accountApi.getAccount(accountId, 
                                       accountWithBalance, 
                                       accountWithBalanceAndCBA, 
                                       AuditLevel.NONE, 
                                       requestOptions);
account_id = "36c05a84-563b-4794-8958-772d93e677e1"
with_balance = false
with_balance_and_cba = false

account = KillBillClient::Model::Account

accountResponse = account.find_by_id( account_id,
                                      with_balance, 
                                      with_balance_and_cba,
                                      options)
accountApi = killbill.AccountApi()

account_id = '36c05a84-563b-4794-8958-772d93e677e1'

account = accountApi.get_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '36c05a84-563b-4794-8958-772d93e677e1';

const response: AxiosResponse<killbill.Account> = await api.getAccount(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '36c05a84-563b-4794-8958-772d93e677e1';

$account = $apiInstance->getAccount($accountID);

Example Response:

{
  "accountId": "36c05a84-563b-4794-8958-772d93e677e1",
  "name": "John Doe",
  "firstNameLength": null,
  "externalKey": "36c05a84-563b-4794-8958-772d93e677e1",
  "email": "john@laposte.com",
  "billCycleDayLocal": 0,
  "currency": "USD",
  "parentAccountId": null,
  "isPaymentDelegatedToParent": false,
  "paymentMethodId": null,
  "referenceTime": "2023-03-08T16:31:16.000Z",
  "timeZone": "UTC",
  "address1": null,
  "address2": null,
  "postalCode": null,
  "company": null,
  "city": null,
  "state": null,
  "country": null,
  "locale": null,
  "phone": null,
  "notes": null,
  "isMigrated": null,
  "accountBalance": null,
  "accountCBA": null,
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
accountWithBalance boolean false false If true, returns accountBalance info
accountWithBalanceAndCBA boolean false false If true, returns accountBalance and accountCBA info
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and an account object in the response body.

Retrieve an Account by its external key

Retrieves the resource object for an Account using its externalKey as an identifier.

HTTP Request

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

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/accounts?externalKey=36c05a84-563b-4794-8958-772d93e677e1"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

String externalKey = "36c05a84-563b-4794-8958-772d93e677e1";
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info

Account result = accountApi.getAccountByKey(externalKey, 
                                            accountWithBalance, 
                                            accountWithBalanceAndCBA, 
                                            AuditLevel.NONE, 
                                            requestOptions);
external_key = '36c05a84-563b-4794-8958-772d93e677e1'
with_balance = false
with_balance_and_cba = false

account = KillBillClient::Model::Account

accountResponse = account.find_by_external_key( external_key,
                                                with_balance,
                                                with_balance_and_cba, 
                                                options)
accountApi = killbill.AccountApi()

external_key = '36c05a84-563b-4794-8958-772d93e677e1'

account = accountApi.get_account_by_key(external_key)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const externalKey = 'external_key';

const response: AxiosResponse<killbill.Account, any> = await api.getAccountByKey(externalKey);
$apiInstance = $client->getAccountApi();

$externalKey = 'external_key';

$account = $apiInstance->getAccountByKey($externalKey);

Example Response:

{
  "accountId": "36c05a84-563b-4794-8958-772d93e677e1",
  "name": "John Doe",
  "firstNameLength": null,
  "externalKey": "36c05a84-563b-4794-8958-772d93e677e1",
  "email": "john@laposte.com",
  "billCycleDayLocal": 0,
  "currency": "USD",
  "parentAccountId": null,
  "isPaymentDelegatedToParent": false,
  "paymentMethodId": null,
  "referenceTime": "2023-03-08T16:31:16.000Z",
  "timeZone": "UTC",
  "address1": null,
  "address2": null,
  "postalCode": null,
  "company": null,
  "city": null,
  "state": null,
  "country": null,
  "locale": null,
  "phone": null,
  "notes": null,
  "isMigrated": null,
  "accountBalance": null,
  "accountCBA": null,
  "auditLogs": []
}

Query Parameters

Name Type Required Default Description
externalKey string true none External key to be used for retrieval
accountWithBalance boolean false false If true, returns accountBalance info
accountWithBalanceAndCBA boolean false false If true, returns accountBalance and accountCBA info
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and an account object in the response body.

Update an Account

Updates selected attributes in an account object. Note that the following fields are not updatable; they can only be set once when creating the original Account: externalKey, currency, timeZone, and referenceTime. In addition, the billCycleDayLocal can be updated but only once, that is, one can create an Account without specifying the billCycleDayLocal and later update its value. This, allows the system to update its value to a good default, that is one that will avoid leading prorations, when creating the first subscription. Also, the audit logs cannot be changed.

The updates are passed in the request body, as an object that only needs to contain the attributes to be changed. Any attribute omitted from the request body will remain unchanged.

If the boolean query parameter treatNullAsReset is true, any attribute specified as null in the request will be set to null. If the parameter is false, any attribute specified as null in the request will remain unchanged.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}

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 "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "name": "Another Name"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d"    
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

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

Account body = new Account();
body.setAccountId(accountId);
body.setName("Another Name");

Boolean treatNullAsReset = false; // any attribute with a null value in the request body will be unchanged
                                  // If set to true, you will need to explicitly set the externalKey, currency and timezone fields to their original values, otherwise a KillBillClientException will occur.

accountApi.updateAccount(accountId, 
                         body, 
                         treatNullAsReset,
                         requestOptions);
account = KillBillClient::Model::Account.new

user = 'user'
reason = 'reason'
comment = 'comment'

account.account_id = "07c0cef4-41c5-4606-b2cd-661332cdd41c"
account.name = 'Another Name'

treat_null_as_reset = false

account.update(treat_null_as_reset,user,reason,comment,options)
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

body = Account(name='Another Name')

accountApi.update_account(account_id,
                          body,
                          created_by='demo',
                          reason='reason', 
                          comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.Account = {name: 'Another Name'}; 

api.updateAccount(body,'07c0cef4-41c5-4606-b2cd-661332cdd41c','created_by');
$apiInstance = $client->getAccountApi();

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

$account = new Account();

$account->setName('Another Name');
$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

$apiInstance->updateAccount($account,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);

Query Parameters

Name Type Required Default Description
treatNullAsReset boolean false false If true, any attribute with a null value in the request body will be set to null. If false, any attribute with a null value in the request body will be unchanged.

Response

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

Close account

This endpoint can be used when no other state change will occur on this Account to bring it to a stable state. Depending on the value of the query parameters it will potentially cancel all active subscriptions, write-off unpaid invoices, etc. This endpoint is not for account deletion. We provide no support to remove state through APIs; such deletion operations, if really needed, would have to happen at the database level and are not encouraged. They can be tricky to get right.

HTTP Request

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/8785164f-b5d7-4da1-9495-33f5105e8d80"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
Boolean cancelAllSubscriptions = true; // Will cancel all subscriptions
Boolean writeOffUnpaidInvoices = true; // Will write off unpaid invoices
Boolean itemAdjustUnpaidInvoices = false; // Will not adjust unpaid invoices
Boolean removeFutureNotifications = true; // Will remove future notifications 

accountApi.closeAccount(accountId, 
                        cancelAllSubscriptions, 
                        writeOffUnpaidInvoices, 
                        itemAdjustUnpaidInvoices, 
                        removeFutureNotifications, 
                        requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = "864c1418-e768-4cd5-a0db-67537144b685"

user = 'user'
reason = 'reason'
comment = 'comment'

cancel_subscriptions = false
writeoff_unpaid_invoices = false
item_adjust_unpaid_invoices = false

account.close(cancel_subscriptions, 
              writeoff_unpaid_invoices, 
              item_adjust_unpaid_invoices,
              user,
              reason,
              comment, 
              options)
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.close_account( account_id,
                          created_by='demo',
                          reason='reason', 
                          comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

api.closeAccount(accountID,'created_by');
$apiInstance = $client->getAccountApi();

$xKillbillCreatedBy = "user";
$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

$apiInstance->closeAccount($accountID,$xKillbillCreatedBy);

Query Parameters

Name Type Required Default Description
cancelAllSubscriptions boolean false false If true, cancel all subscriptions
writeOffUnpaidInvoices boolean false false If true, write off unpaid invoices
itemAdjustUnpaidInvoices boolean false false If true, adjust unpaid invoices
removeFutureNotifications boolean false false If true, remove future notifications

Response

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

These endpoints allow you to list all accounts or to search for a specific account.

List accounts

Retrieve a list of all account records.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/pagination

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/accounts/pagination"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

Long offset = 0L;
Long limit = 1L;
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info

Accounts allAccounts = accountApi.getAccounts(offset,
                                              limit,
                                              accountWithBalance,
                                              accountWithBalanceAndCBA,
                                              AuditLevel.NONE,
                                              requestOptions);
account = KillBillClient::Model::Account

offset = 0
limit = 100
with_balance = false
with_balance_and_cba = false

allAccounts = account.find_in_batches( offset,
                                       limit,
                                       with_balance,
                                       with_balance_and_cba,
                                       options)
accountApi = killbill.AccountApi()

allAccounts = accountApi.get_accounts()
const api: killbill.AccountApi = new killbill.AccountApi(config);

const response: AxiosResponse<killbill.Account[], any> = await api.getAccounts();
$apiInstance = $client->getAccountApi();

$accounts = $apiInstance->getAccounts();

Example Response:

{
  "next": [
    {
      "auditLogs": [],
      "externalKey": "e60a79de-0d4c-4aeb-82e9-7695fe393b81",
      "accountId": "e60a79de-0d4c-4aeb-82e9-7695fe393b81",
      "referenceTime": {
        "year": 2023,
        "dayOfYear": 65,
        "equalNow": false,
        "weekyear": 2023,
        "chronology": {
          "zone": {
            "ID": "UTC"
          }
        },
        "weekOfWeekyear": 10,
        "secondOfMinute": 39,
        "millisOfDay": 61959000,
        "monthOfYear": 3,
        "dayOfWeek": 1,
        "beforeNow": true,
        "minuteOfDay": 1032,
        "dayOfMonth": 6,
        "era": 1,
        "zone": {
          "ID": "UTC"
        },
        "yearOfCentury": 23,
        "centuryOfEra": 20,
        "hourOfDay": 17,
        "secondOfDay": 61959,
        "millis": 1678122759000,
        "yearOfEra": 2023,
        "minuteOfHour": 12,
        "millisOfSecond": 0,
        "afterNow": false
      },
      "paymentDelegatedToParent": false,
      "name": "John Doe",
      "timeZone": "UTC",
      "currency": "USD",
      "billCycleDayLocal": 0,
      "email": "john@laposte.com"
    }
  ],
  "paginationNextOffset": 1,
  "paginationNextPageUri": "/1.0/kb/accounts/pagination?offset=1&limit=1&accountWithBalanceAndCBA=false&accountWithBalance=false&audit=NONE",
  "paginationMaxNbRecords": 5,
  "killBillHttpClient": {},
  "paginationCurrentOffset": 0,
  "paginationTotalNbRecords": 5,
  "empty": false
}

Query Parameters

Name Type Required Default Description
offset long false 0 Starting index for items listed
limit long false 100 Maximum number of items to be listed
accountWithBalance boolean false false If true, returns accountBalance info
accountWithBalanceAndCBA boolean false false If true, returns accountBalance and accountCBA info

Response

If successful, returns a status code of 200 and a list of all accounts.

Search accounts

Search for an account by a specified search string. Search operation can be of two types as follows:

Basic:

The search string is compared to the following attributes: accountId, name, email, companyName, and externalKey. The operation returns the account record in which the search string matches all or part of any one of the attributes name, email, companyName, externalKey. However, the string must match the entire attribute in case of accountId.

For example : An account with name exampleaccount can be searched using example as the search string. However, an account with accountId 9254283b-be25-45f1-97c3-b902f4d18bab cannot be searched using only 9254283b as the search string.

Advanced:

Advanced search allows filtering on the specified fields. The prefix marker _q=1 needs to be specified at the beginning of the search key to indicate this is an advanced query.

The search key should be in the following format: <field>[<operator>]=value. Here:

Some advanced search key examples:

Note: The symbols [,],% need to be URL encoded while using cURL/Postman as follows:

Symbol Encoding
[ %5B
] %5D
% %25

HTTP Request

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

Example Request:

## Basic Search
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/accounts/search/John%20Doe"


## Advanced Search (search by email and currency)
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/accounts/search/_q=1&email=john@acme.com&currency=USD"

## Advanced Search (search with operator)
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/accounts/search/_q=1&email%5Blike%5D=john%25"    
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

String searchKey = "John";
Long offset = 0L;
Long limit = 1L;
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info

List<Account> accountsByKey = accountApi.searchAccounts(searchKey, 
                                                        offset,
                                                        limit,
                                                        accountWithBalance,
                                                        accountWithBalanceAndCBA,
                                                        AuditLevel.NONE,
                                                        requestOptions);
account = KillBillClient::Model::Account

search_key = 'John'
offset = 0
limit = 100
with_balance = false
with_balance_and_cba = false

accounts = account.find_in_batches_by_search_key( search_key,
                                                  offset,
                                                  limit,
                                                  with_balance,
                                                  with_balance_and_cba,
                                                  options)
accountApi = killbill.AccountApi()

search_key = 'John'

accounts = accountApi.search_accounts(search_key)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const searchKey = 'search_key';

const response: AxiosResponse<killbill.Account[], any> = await api.searchAccounts(searchKey);
$apiInstance = $client->getAccountApi();

$searchKey = 'search_key';

$accounts = $apiInstance->searchAccounts($searchKey);

Example Response:

{
  "next": [
    {
      "auditLogs": [],
      "accountId": "fc693517-9ede-4543-a184-9e6f21119584",
      "externalKey": "fc693517-9ede-4543-a184-9e6f21119584",
      "referenceTime": {
        "year": 2023,
        "dayOfYear": 65,
        "equalNow": false,
        "weekyear": 2023,
        "chronology": {
          "zone": {
            "ID": "UTC"
          }
        },
        "weekOfWeekyear": 10,
        "secondOfMinute": 21,
        "millisOfDay": 62241000,
        "monthOfYear": 3,
        "dayOfWeek": 1,
        "beforeNow": true,
        "minuteOfDay": 1037,
        "dayOfMonth": 6,
        "era": 1,
        "zone": {
          "ID": "UTC"
        },
        "yearOfCentury": 23,
        "hourOfDay": 17,
        "centuryOfEra": 20,
        "secondOfDay": 62241,
        "millis": 1678123041000,
        "yearOfEra": 2023,
        "minuteOfHour": 17,
        "millisOfSecond": 0,
        "afterNow": false
      },
      "paymentDelegatedToParent": false,
      "name": "John Doe",
      "timeZone": "UTC",
      "currency": "USD",
      "billCycleDayLocal": 0,
      "email": "john@laposte.com"
    }
  ],
  "paginationNextOffset": 1,
  "paginationNextPageUri": "/1.0/kb/accounts/search/John?offset=1&limit=1&accountWithBalanceAndCBA=false&accountWithBalance=false&audit=NONE",
  "paginationMaxNbRecords": 5,
  "killBillHttpClient": {},
  "paginationCurrentOffset": 0,
  "paginationTotalNbRecords": 4,
  "empty": false
}

Query Parameters

Name Type Required Default Description
offset long false 0 Starting index for items listed
limit long false 100 Maximum number of items to return on this page
accountWithBalance boolean false false If true, returns accountBalance info
accountWithBalanceAndCBA boolean false false If true, returns accountBalance and accountCBA info
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a list of accounts that contain a match for the specified search key.

Email

These endpoints manage emails associated with a customer account. These are secondary emails, distinct from the email attribute in the account object. It is possible to have several such emails for one customer account.

Add account email

Add an email to an account. Existing emails are undisturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails

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 '{ "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "email": "email@laposte.com"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("873c26ef-a3fa-4942-b2f5-549b51f20b1a");
String email = "email@laposte.com";

AccountEmail accountEmail = new AccountEmail(accountId,
                                             email,
                                             AuditLevel.NONE);

accountApi.addEmail(accountId,
                    accountEmail,
                    requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '873c26ef-a3fa-4942-b2f5-549b51f20b1a'

email = 'email@laposte.com'

account.add_email(email,
                  user,
                  reason,
                  comment,
                  options)
accountApi = killbill.AccountApi()

account_id = 'c84de569-b654-4f7f-ab13-17616302d310'
body = AccountEmail(account_id=account_id, email='email@laposte.com')

accountApi.add_email( account_id,
                      body,
                      created_by='demo',
                      reason='reason', 
                      comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.AccountEmail = { email: 'email@laposte.com' };

api.addEmail(body, '03fc2b57-06be-4691-a260-c897d5c1e13e', 'created_by');
$apiInstance = $client->getAccountApi();

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

$accountEmail = new AccountEmail();

$accountEmail->setEmail('email@laposte.com');
$accountEmail->setAccountId('03fc2b57-06be-4691-a260-c897d5c1e13e');

$accountID = '03fc2b57-06be-4691-a260-c897d5c1e13e';

$apiInstance->addEmail($accountEmail,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);

Request Body

The request body identifies a subset of the account attributes as a JSON string. The attributes required are accountId and email (the email to be added). accountId is required in the body even though it is given in the path. No other attributes should be included.

Query Parameters

None.

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the account object, including the accountId.

Retrieve account emails

Retrieves all emails for an account

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("cd026587-c93b-471c-a98d-224c21636fbc");

List<AccountEmail> emails = accountApi.getEmails(accountId, requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'cd026587-c93b-471c-a98d-224c21636fbc'

audit = 'NONE'

accountEmails = account.emails(audit, options)
accountApi = killbill.AccountApi()

account_id = 'c8f51346-562d-429b-8c89-27a0f72009b3'

accountEmails = accountApi.get_emails(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'f7fde238-850a-4a7b-b075-48b582ee3495';

const response: AxiosResponse<killbill.AccountEmail[], any> = await api.getEmails(accountID);
$apiInstance = $client->getAccountApi();

$accountID = 'f7fde238-850a-4a7b-b075-48b582ee3495';

$emails  = $apiInstance->getEmails($accountID);

Example Response:

[
  {
  "accountId":"e4ca38b3-934d-42e8-a292-ffb0af5549f2",
  "email":"email@laposte.com"
  }
]

Query Parameters

None.

Response Body

If successful, returns a status code of 200 and a list of objects giving the account id and the emails. Note that this is not the full object for each email, and does not include the email ID. This can be obtained only from the account audit log.

Delete email

Deletes an email from an account

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails/{email}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails/email@laposte.com"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("873c26ef-a3fa-4942-b2f5-549b51f20b1a");
String email = "email@laposte.com";

accountApi.removeEmail(accountId, 
                       email, 
                       requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = 'f755e6a9-cf56-4776-9455-3df350b72f6d'

email = 'email@laposte.com'

account.remove_email(email,
                     user,
                     reason,
                     comment,
                     options)
accountApi = killbill.AccountApi()

account_id = 'c84de569-b654-4f7f-ab13-17616302d310'
email = 'email@laposte.com'

accountApi.remove_email(account_id,
                        email,
                        created_by='demo',
                        reason='reason', 
                        comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'be484bff-58dc-4ceb-906f-61dc9e317b0f';

const email = 'email@laposte.com';

api.removeEmail(accountID,email,'created_by');
$apiInstance = $client->getAccountApi();

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

$accountID = 'be484bff-58dc-4ceb-906f-61dc9e317b0f';
$accountEmail = 'email@laposte.com';

$apiInstance->removeEmail($accountID,$accountEmail,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Query Parameters

None.

Response

If successful, returns a status code of 204 and without any data.

Bundle

This endpoint provides an API to list the Bundles associated with this account. A Bundle is a set of Subscriptions and related information. See Bundle for details on Bundles.

Retrieve bundles for account

This endpoint is used to list all Bundles associated with this account. It is possible to limit the list to a specific Bundle external key, or to a list of Bundle Ids.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/bundles

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/bundles" 
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("15434b45-54c1-4a44-851c-b1f2f7a52f03");
String externalKey = "123467"; //use null to fetch all bundles
String bundlesFilter = null;

List<Bundle> accountBundles = accountApi.getAccountBundles(accountId, 
                                                           externalKey, 
                                                           bundlesFilter,
                                                           AuditLevel.NONE,
                                                           requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '15434b45-54c1-4a44-851c-b1f2f7a52f03'

accountBundles = account.bundles(options)
accountApi = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountBundles = accountApi.get_account_bundles(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

const response: AxiosResponse<killbill.Bundle[], any> = await api.getAccountBundles(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

$bundles  = $apiInstance-> getAccountBundles($accountID);

Example Response:

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "subscriptions": [
      {
        "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
        "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
        "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "startDate": "2018-07-18",
        "productName": "Standard",
        "productCategory": "BASE",
        "billingPeriod": "MONTHLY",
        "phaseType": "TRIAL",
        "priceList": "DEFAULT",
        "planName": "standard-monthly",
        "state": "ACTIVE",
        "sourceType": "NATIVE",
        "cancelledDate": null,
        "chargedThroughDate": null,
        "billingStartDate": "2018-07-18",
        "billingEndDate": null,
        "billCycleDayLocal": 17,
        "events": [
          {
            "eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-18",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "START_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_STARTED",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-18",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "START_BILLING",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "billing-service",
            "serviceStateName": "START_BILLING",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-08-17",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "PHASE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement+billing-service",
            "serviceStateName": "PHASE",
            "phase": "standard-monthly-evergreen",
            "auditLogs": []
          }
        ],
        "priceOverrides": null,
        "prices": [
          {
            "planName": "standard-monthly",
            "phaseName": "standard-monthly-trial",
            "phaseType": "TRIAL",
            "fixedPrice": 0,
            "recurringPrice": null,
            "usagePrices": []
          },
          {
            "planName": "standard-monthly",
            "phaseName": "standard-monthly-evergreen",
            "phaseType": "EVERGREEN",
            "fixedPrice": null,
            "recurringPrice": 100,
            "usagePrices": []
          }
        ],
        "auditLogs": []
      }
    ],
    "timeline": {
      "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "events": [
        {
          "eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-18",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "START_ENTITLEMENT",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "entitlement-service",
          "serviceStateName": "ENT_STARTED",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-18",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "START_BILLING",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "billing-service",
          "serviceStateName": "START_BILLING",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-08-17",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "PHASE",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "entitlement+billing-service",
          "serviceStateName": "PHASE",
          "phase": "standard-monthly-evergreen",
          "auditLogs": []
        }
      ],
      "auditLogs": []
    },
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
externalKey string false return all bundles Bundle external key; if present, return only bundles with this key.
bundlesFilter string false return all bundles Comma separated list of bundle ids to return, if found.
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Returns

If successful, returns a status code of 200 and a list of bundle objects.

Retrieve paginated bundles for account

This endpoint is used to list all Bundles associated with this account in a paginated format.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/bundles/pagination

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/accounts/325fbe1c-7c35-4d96-a4e5-2cbaabe218c6/bundles/pagination" 
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("325fbe1c-7c35-4d96-a4e5-2cbaabe218c6");
Long offset = 0L;
Long limit = 10L;       

Bundles bundles = accountApi.getAccountBundlesPaginated(accountId, offset, limit, AuditLevel.NONE, requestOptions);

account_id = '325fbe1c-7c35-4d96-a4e5-2cbaabe218c6'
offset = 0
limit = 100
audit = 'NONE'

bundles = KillBillClient::Model::Account.paginated_bundles(account_id, offset, limit, audit, options)
accountApi = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountBundles = accountApi.get_account_bundles_paginated(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

const response: AxiosResponse<killbill.Bundle[], any> = await api.getAccountBundlesPaginated(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

$bundles  = $apiInstance-> getAccountBundlesPaginated($accountID);

Example Response:

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "subscriptions": [
      {
        "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
        "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
        "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "startDate": "2018-07-18",
        "productName": "Standard",
        "productCategory": "BASE",
        "billingPeriod": "MONTHLY",
        "phaseType": "TRIAL",
        "priceList": "DEFAULT",
        "planName": "standard-monthly",
        "state": "ACTIVE",
        "sourceType": "NATIVE",
        "cancelledDate": null,
        "chargedThroughDate": null,
        "billingStartDate": "2018-07-18",
        "billingEndDate": null,
        "billCycleDayLocal": 17,
        "events": [
          {
            "eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-18",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "START_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_STARTED",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-18",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "START_BILLING",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "billing-service",
            "serviceStateName": "START_BILLING",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-08-17",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "PHASE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement+billing-service",
            "serviceStateName": "PHASE",
            "phase": "standard-monthly-evergreen",
            "auditLogs": []
          }
        ],
        "priceOverrides": null,
        "prices": [
          {
            "planName": "standard-monthly",
            "phaseName": "standard-monthly-trial",
            "phaseType": "TRIAL",
            "fixedPrice": 0,
            "recurringPrice": null,
            "usagePrices": []
          },
          {
            "planName": "standard-monthly",
            "phaseName": "standard-monthly-evergreen",
            "phaseType": "EVERGREEN",
            "fixedPrice": null,
            "recurringPrice": 100,
            "usagePrices": []
          }
        ],
        "auditLogs": []
      }
    ],
    "timeline": {
      "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "events": [
        {
          "eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-18",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "START_ENTITLEMENT",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "entitlement-service",
          "serviceStateName": "ENT_STARTED",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-18",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "START_BILLING",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "billing-service",
          "serviceStateName": "START_BILLING",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-08-17",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "PHASE",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "entitlement+billing-service",
          "serviceStateName": "PHASE",
          "phase": "standard-monthly-evergreen",
          "auditLogs": []
        }
      ],
      "auditLogs": []
    },
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
offset long false 0 Starting index for items listed
limit long false 100 Maximum number of items to be listed
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Returns

If successful, returns a status code of 200 and a list of bundle objects.

Invoice

This endpoint provides an API to list the Invoices associated with this account. See section Invoice for details on invoices.

Retrieve account invoices

List the Invoices associated with this account. Note that this endpoint returns shallow invoices (the value 0 is returned for the amount, creditAdj, refundAdj and balance fields) unless includeInvoiceComponents=true is specified.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoices"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("d3a82897-ae72-4a2e-9bca-e3c1fe087f84");
LocalDate startDate = null;
LocalDate endDate = null;
Boolean withMigrationInvoices = false; // Will not fetch migrated invoice - if any
Boolean unpaidInvoicesOnly = false; // Will not restrict to unpaid invoices
Boolean includeVoidedInvoices = false; // Will not include void invoices
Boolean includeInvoiceComponents = false; //Will not include invoice components like invoice items/payments, etc.
String invoicesFilter = null;
Invoices invoices = accountApi.getInvoicesForAccount(accountId,
                                                      startDate, 
                                                      endDate,
                                                      withMigrationInvoices,
                                                      unpaidInvoicesOnly,
                                                      includeVoidedInvoices,
                                                      includeInvoiceComponents,
                                                      invoicesFilter,
                                                      AuditLevel.FULL,
                                                      requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountInvoices = account.invoices(options)
accountApi = killbill.AccountApi()

account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountInvoices = accountApi.get_invoices_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

const response: AxiosResponse<killbill.Invoice[], any> = await api.getInvoicesForAccount(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

$invoices  = $apiInstance-> getInvoicesForAccount($accountID);

Example Response:

[
   {
      "amount":50.0,
      "currency":"USD",
      "status":"COMMITTED",
      "creditAdj":0.0,
      "refundAdj":0.0,
      "invoiceId":"d981abbb-3622-487a-9564-d594c9d04f83",
      "invoiceDate":"2013-08-01",
      "targetDate":"2013-08-01",
      "invoiceNumber":"1563",
      "balance":0.0,
      "accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "items":[
         {
            "invoiceItemId":"5f3b4e9c-66bd-4c5c-b84a-4ae951cc2f1d",
            "invoiceId":"d981abbb-3622-487a-9564-d594c9d04f83",
            "accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
            "itemType":"EXTERNAL_CHARGE",
            "description":"Some description",
            "startDate":"2013-08-01",
            "amount":50.0,
            "currency":"USD",
            "auditLogs":[]
         }
      ],
      "isParentInvoice":false,
      "auditLogs":[]
   }
]

Query Parameters

Name Type Required Default Description
startDate date false no starting date Return only invoices issued since this date.
endDate date false no ending date Return only invoices issued up to this date.
withMigrationInvoices boolean false false Choose true to include migration invoices
unpaidInvoicesOnly boolean false false Choose true to include unpaid invoices only
includeVoidedInvoices boolean false false Choose true to include voided invoices
includeInvoiceComponents boolean false false Choose true to include invoice components (like invoice items/payments, etc.)
invoicesFilter string false empty A comma separated list of invoiceIds to filter
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

For information about migration and migration invoices, see the Migration Guide.

Response

If successful, returns a status of 200 and a list of invoice objects for this account.

Retrieve paginated account invoices

List the Invoices associated with this account in a paginated format. Note that this endpoint return shallow objects (the value 0 is returned for the amount, creditAdj, refundAdj and balance fields). In order to retrieve the account invoices with the actual data for these fields, you could use the non-paginated retrieve account invoices endpoint with includeInvoiceComponents=true. Alternatively, you could also use the retrieve invoice by id to obtain the complete invoice data for an individual invoice.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices/pagination

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/accounts/325fbe1c-7c35-4d96-a4e5-2cbaabe218c6/invoices/pagination"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("325fbe1c-7c35-4d96-a4e5-2cbaabe218c6");
Long offset = 0L;
Long limit = 10L;       
Invoices invoices = accountApi.getInvoicesForAccountPaginated(accountId, offset, limit, AuditLevel.NONE, requestOptions);

account_id = '325fbe1c-7c35-4d96-a4e5-2cbaabe218c6'
offset = 0
limit = 100
audit = 'NONE'

invoices = KillBillClient::Model::Account.paginated_invoices(account_id, offset, limit, audit, options)
accountApi = killbill.AccountApi()

account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountInvoices = accountApi.get_invoices_for_account_paginated(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

const response: AxiosResponse<killbill.Invoice[], any> = await api.getInvoicesForAccountPaginated(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

$invoices  = $apiInstance-> getInvoicesForAccountPaginated($accountID);

Example Response:

[
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "92d62ac0-606a-4f31-bb83-e03883cff710",
    "invoiceDate": "2024-09-19",
    "targetDate": "2024-09-19",
    "invoiceNumber": "46166",
    "balance": 0,
    "accountId": "73c90e84-42dc-406a-be87-b75c45e581a2",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "trackingIds": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
offset long false 0 Starting index for items listed
limit long false 100 Maximum number of items to be listed
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

For information about migration and migration invoices, see the Migration Guide.

Response

If successful, returns a status of 200 and a list of invoice objects for this account.

Payment

These endpoints are used to make or manage payments associated with this account. See section Payment for details on payments.

Trigger a payment for all unpaid invoices

Initiate payments for any unpaid invoices. This API allows you to make a series of payment calls, one against each unpaid invoice, using a specific payment method.

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for fetching the paid invoices. If no payments were made, returns a 204 status code.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoicePayments

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoicePayments?paymentMethodId=f835c556-0694-4883-b4c1-d1b6e308409b"   
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e011caa5-ba35-4ac6-81cb-63b4f08122dc");
UUID paymentMethodId = null;
Boolean externalPayment = true; // Will use a external payment method
BigDecimal paymentAmount = null;
LocalDate targetDate = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.payAllInvoices(accountId, 
                          paymentMethodId, 
                          externalPayment, 
                          paymentAmount, 
                          targetDate,
                          NULL_PLUGIN_PROPERTIES, 
                          requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

invoice_payment                  = KillBillClient::Model::InvoicePayment.new
invoice_payment.account_id       = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

external_payment  = true
payment_method_id = nil
target_date       = nil

invoice_payment.bulk_create(external_payment,
                            payment_method_id,
                            target_date,
                            user,
                            reason,
                            comment,
                            options)
accountApi = killbill.AccountApi()

account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountApi.pay_all_invoices(account_id,                                                      
                            external_payment=True,
                            payment_method_id=None,
                            target_date=None,
                            created_by='demo',
                            reason='reason', 
                            comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

api.payAllInvoices(accountID,'created_by');
$apiInstance = $client->getAccountApi();

$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';

$xKillbillCreatedBy = "user";

$apiInstance-> payAllInvoices($accountID,$xKillbillCreatedBy);

Query Parameters

Name Type Required Default Description
paymentMethodId string false default payment method Payment method id
externalPayment boolean false false Choose true if you use a external payment method.
paymentAmount string false total balance Total payment amount
targetDate string false current date Date for which payment should be made

Response

If successful, returns a status code of 204 without any data.

Retrieve account invoice payments

Retrieve a list of payments made against invoices for this account.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoicePayments

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoicePayments"    
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e011caa5-ba35-4ac6-81cb-63b4f08122dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

InvoicePayments result = accountApi.getInvoicePayments(accountId, 
                                                       NULL_PLUGIN_PROPERTIES, 
                                                       requestOptions);
audit ='NONE'
with_plugin_info = false
with_attempts = false

account = KillBillClient::Model::Account.new

account.account_id = 'e011caa5-ba35-4ac6-81cb-63b4f08122dc'

accountInvoicePayments = account.invoice_payments( audit,
                                                   with_plugin_info,
                                                   with_attempts,
                                                   options)
accountApi = killbill.AccountApi()

account_id = '110952d7-1b7e-482c-b6bb-103e46794927'

accountInvoicePayments = accountApi.get_invoice_payments(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '110952d7-1b7e-482c-b6bb-103e46794927';

const response: AxiosResponse<killbill.InvoicePayment[], any> = await api.getInvoicePayments(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '110952d7-1b7e-482c-b6bb-103e46794927';

$invoicePayments  = $apiInstance-> getInvoicePayments($accountID);

Example Response:

[
   {
      "targetInvoiceId":"d1d6e8d8-c476-4b53-badf-c23f78c02c09",
      "accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "paymentId":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
      "paymentNumber":"319",
      "paymentExternalKey":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
      "authAmount":0,
      "capturedAmount":0,
      "purchasedAmount":50.0,
      "refundedAmount":0,
      "creditedAmount":0,
      "currency":"USD",
      "paymentMethodId":"6c064894-60cb-4d7e-a679-7b2464522968",
      "transactions":[
         {
            "transactionId":"91c7363c-76b9-48f5-aafa-f098d4470a2a",
            "transactionExternalKey":"91c7363c-76b9-48f5-aafa-f098d4470a2a",
            "paymentId":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
            "paymentExternalKey":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
            "transactionType":"PURCHASE",
            "amount":50.0,
            "currency":"USD",
            "effectiveDate":"2013-08-01T06:00:01.000Z",
            "processedAmount":50.0,
            "processedCurrency":"USD",
            "status":"SUCCESS",
            "auditLogs":[]
         }
      ],
      "auditLogs":[]
   }
]

Query Parameters

Name Type Required Default Description
withPluginInfo boolean false false Choose true to include plugin info
withAttempts boolean false false Choose true to include payment attempts
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Returns

If successful, returns a status code of 200 and a list of invoice payment objects.

Retrieve account payments

Retrieve a list of payments made for this account. Payments are listed independent of any invoice.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/payments

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/payments"   
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e0fe95af-7d59-4b70-8252-165e1840410c");
Boolean withAttempts = false; // Will not reflect payment attempts
Boolean withPluginInfo = false; // Will not reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = accountApi.getPaymentsForAccount(accountId,
                                                     withAttempts,
                                                     withPluginInfo,
                                                     NULL_PLUGIN_PROPERTIES, 
                                                     AuditLevel.NONE,
                                                     requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'

accoountPayments = account.payments(options)
accountApi = killbill.AccountApi()

account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'

accountPayments = accountApi.get_payments_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

const response: AxiosResponse<killbill.InvoicePayment[], any> = await api.getPaymentsForAccount(accountID);
$apiInstance = $client->getAccountApi();

$accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

$accountPayments  = $apiInstance-> getPaymentsForAccount($accountID);

Example Response:

[
   {
      "accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "paymentId":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
      "paymentNumber":"325",
      "paymentExternalKey":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
      "authAmount":0,
      "capturedAmount":0,
      "purchasedAmount":50.0,
      "refundedAmount":0,
      "creditedAmount":0,
      "currency":"USD",
      "paymentMethodId":"6041ffab-ae5f-45d3-bdf8-ce8cbfa5fd5c",
      "transactions":[
         {
            "transactionId":"be9dceca-9c5d-4038-818c-57e6fccfbe92",
            "transactionExternalKey":"be9dceca-9c5d-4038-818c-57e6fccfbe92",
            "paymentId":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
            "paymentExternalKey":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
            "transactionType":"PURCHASE",
            "amount":50.0,
            "currency":"USD",
            "effectiveDate":"2013-08-01T06:00:02.000Z",
            "processedAmount":50.0,
            "processedCurrency":"USD",
            "status":"SUCCESS",
            "auditLogs":[

            ]
         }
      ],
      "auditLogs":[]
   }
]

Query Parameters

Name Type Required Default Description
withPluginInfo boolean false false Choose true to include plugin info
withAttempts boolean false false Choose true to include payment attempts
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a list of payment objects.

Trigger a payment (authorization, purchase or credit)

This endpoint is part of the raw payment APIs, unreleated to subscriptions and invoices. It simply triggers a payment transaction against a particular payment gateway through the Kill Bill core and through the plugin communicating with the payment gateway. The transaction could be an authorization, a purchase, or a credit.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/payments

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 '{ "transactionType": "AUTHORIZE", "amount": 0}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/payments?paymentMethodId=c02fa9b0-ae95-42ae-9010-bc11cb160947"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("f4087a76-9f8a-4893-abbf-c5bb69975d1b");

PaymentTransaction authTransaction = new PaymentTransaction();
authTransaction.setAmount(BigDecimal.ONE);
authTransaction.setCurrency(account.getCurrency());

// TransactionType could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
authTransaction.setTransactionType(TransactionType.AUTHORIZE);

UUID paymentMethodId = UUID.fromString("1d55ed5f-deea-4109-98b0-beb13a242f7c");
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = accountApi.processPayment(accountId, 
                                            authTransaction, 
                                            paymentMethodId, 
                                            NULL_PLUGIN_NAMES,
                                            NULL_PLUGIN_PROPERTIES, 
                                            requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

transaction = KillBillClient::Model::Transaction.new
transaction.amount = '50.0'

account_id = "f4087a76-9f8a-4893-abbf-c5bb69975d1b"
payment_method_id = "1d55ed5f-deea-4109-98b0-beb13a242f7c"
refresh_options = nil

# Authorization
transaction.auth(account_id,
                 payment_method_id, 
                 user, 
                 reason, 
                 comment, 
                 options, 
                 refresh_options)

# Purchase
transaction.purchase(account_id,
                     payment_method_id, 
                     user, 
                     reason, 
                     comment, 
                     options, 
                     refresh_options)

# Credit
transaction.credit(account_id,
                   payment_method_id, 
                   user, 
                   reason, 
                   comment, 
                   options, 
                   refresh_options)
accountApi = killbill.AccountApi()

account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
payment_method_id = '80c7b386-97b2-424c-bb4e-0017f92bc6eb'


# transaction_type could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
body = PaymentTransaction(amount=50, transaction_type='AUTHORIZE')

accountApi.process_payment(account_id, 
                           body, 
                           payment_method_id=payment_method_id,                           
                           created_by='demo',                           
                           reason='reason', 
                           comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.PaymentTransaction = {amount: 50, transactionType: 'AUTHORIZE'};

api.processPayment(body,'b0da8392-49ba-43f2-8fac-3f9f85b8ff61','created_by');
$apiInstance = $client->getAccountApi();

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

$paymentTransaction = new PaymentTransaction();

$paymentTransaction->setAmount('50');
$paymentTransaction->setTransactionType('AUTHORIZE');

$accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

$apiInstance-> processPayment($paymentTransaction,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);

Request Body

The request body is a JSON string representing the payment transaction. See section Payment Transaction for details on payment transactions.

Query Parameters

Name Type Required Default Description
paymentMethodId string false default payment method payment method ID to use, if not default method
controlPluginName array of strings false omit list of control plugins, if any
pluginProperty array of strings false omit list of plugin properties, if any

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment object, including the generated paymentId.

Trigger a payment (authorization, purchase or credit) using the account external key

This endpoint performs the same actions as the previous one, but the account is identified by its external key.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/payments

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 '{ "transactionType": "AUTHORIZE", "amount": 0}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/payments?externalKey=2ad52f53-85ae-408a-9879-32a7e59dd03d&paymentMethodId=c02fa9b0-ae95-42ae-9010-bc11cb160947"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

String externalKey = "ad70ffb1-3355-418a-a457-6d8d80696d02";
PaymentTransaction authTransaction = new PaymentTransaction();
authTransaction.setAmount(BigDecimal.ONE);
authTransaction.setCurrency(Currency.USD);//use currency associated with Account

// TransactionType could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
authTransaction.setTransactionType(TransactionType.AUTHORIZE);

UUID paymentMethodId = UUID.fromString("c6bd413e-268e-4cc8-afb0-16b2dec3ffa5");
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = accountApi.processPaymentByExternalKey(authTransaction,
                                                         externalKey, 
                                                          paymentMethodId, 
                                                          NULL_PLUGIN_NAMES,
                                                          NULL_PLUGIN_PROPERTIES, 
                                                          requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

transaction = KillBillClient::Model::Transaction.new
transaction.amount = '50.0'

externalKey = "ad70ffb1-3355-418a-a457-6d8d80696d02";
payment_method_id = 'c6bd413e-268e-4cc8-afb0-16b2dec3ffa5'
refresh_options = nil

# Authorization
transaction.auth_by_external_key(external_key,
                                 payment_method_id, 
                                 user, 
                                 reason, 
                                 comment, 
                                 options, 
                                 refresh_options)

# Purchase
transaction.purchase_by_external_key(external_key,
                                     payment_method_id, 
                                     user, 
                                     reason, 
                                     comment, 
                                     options, 
                                     refresh_options)

# Credit
transaction.credit_by_external_key(external_key,
                                   payment_method_id, 
                                   user, 
                                   reason, 
                                   comment, 
                                   options, 
                                   refresh_options)
accountApi = killbill.AccountApi()

account_external_key = 'sample_external_key'
payment_method_id = '80c7b386-97b2-424c-bb4e-0017f92bc6eb'


# transaction_type could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
body = PaymentTransaction(amount=50, transaction_type='AUTHORIZE')

accountApi.process_payment_by_external_key(body,
                                           account_external_key,
                                           payment_method_id=payment_method_id,
                                           created_by='demo',
                                           reason='reason',
                                           comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.PaymentTransaction = {amount: 50, transactionType: 'AUTHORIZE'};

api.processPaymentByExternalKey(body,'sample_external_key','created_by');
$apiInstance = $client->getAccountApi();

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

$paymentTransaction = new PaymentTransaction();

$paymentTransaction->setAmount('50');
$paymentTransaction->setTransactionType('AUTHORIZE');

$externalKey = 'sample_external_key';

$apiInstance-> processPaymentByExternalKey($paymentTransaction,$xKillbillCreatedBy,$externalKey,$xKillbillReason,$xKillbillComment);

Request Body

The request body is a JSON string representing the payment transaction. See section Payment Transaction for details on payment transactions.

Query Parameters

Name Type Required Default Description
externalKey string true none the account external key
paymentMethodId string false default payment method payment method ID to use, if not default method
controlPluginName array of strings false empty list list of control plugins, if any
pluginProperty array of strings false empty list list of plugin properties, if any

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment object, including the generated paymentId.

Payment Method

These endpoints allow you to manage the payment methods for an account. See section Payment Method for details on payment methods.

Add a payment method

Add a payment method for a given Account. The payment method is represented by a plugin that must already be registered with KillBill.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods

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 '{ "externalKey": "ExternalKey", "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "pluginName": "__EXTERNAL_PAYMENT__"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/8785164f-b5d7-4da1-9495-33f5105e8d80/paymentMethods" 
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("6e5d0912-2e56-4511-af77-af054b616696");
String pluginName = "__EXTERNAL_PAYMENT__"; 

PaymentMethod paymentMethod = new PaymentMethod();
paymentMethod.setPluginName(pluginName);
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

//create a payment method
PaymentMethod paymentMethodPP = accountApi.createPaymentMethod(accountId, paymentMethod, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);

//to create a payment method and set it as default use accountApi.createPaymentMethod(accountId, body, isDefault, payAllUnpaidInvoices, controlPluginName, pluginProperty, inputOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

pm             = KillBillClient::Model::PaymentMethod.new
pm.account_id  = "6e5d0912-2e56-4511-af77-af054b616696"
pm.plugin_name = '__EXTERNAL_PAYMENT__'
pm.plugin_info = nil

is_default = true

pm.create(is_default, 
          user, 
          reason, 
          comment,
          options)
accountApi = killbill.AccountApi()

account_id = '059ecfb8-6b4d-4a89-9537-63a687e6cf10'
body = PaymentMethod(external_key='ExternalKey', plugin_name='__EXTERNAL_PAYMENT__', plugin_info=None)


accountApi.create_payment_method(account_id, 
                                 body, 
                                 created_by='demo',
                                 reason='reason', 
                                 comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.PaymentMethod = {externalKey: 'ExternalKey', pluginName: '__EXTERNAL_PAYMENT__'}

api.createPaymentMethod(body,'059ecfb8-6b4d-4a89-9537-63a687e6cf10','created_by');
$apiInstance = $client->getAccountApi();

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

$paymentMethod = new PaymentMethod();

$paymentMethod->setExternalKey("ExternalKey");
$paymentMethod-> setPluginName('__EXTERNAL_PAYMENT__');

$accountID = "059ecfb8-6b4d-4a89-9537-63a687e6cf10";

$apiInstance-> createPaymentMethod($paymentMethod,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);

Request Body

A payment method object specifying accountId and pluginName at the minimum. Please refer to the payment method resource section for more details about the fields.

Query Parameters

Name Type Required Default Description
isDefault boolean false false Choose true to set new payment as default.
payAllUnpaidInvoices boolean false false Choose true to pay all unpaid invoices.
controlPluginName array of strings false empty list list of control plugins, if any
pluginProperty array of strings false empty list list of plugin properties, if any

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment method, including the generated paymentMethodId.

Retrieve account payment methods

This API retrieves a list of the payment methods that are associated with this account.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

List<PaymentMethod> paymentMethods = accountApi.getPaymentMethodsForAccount(accountId, 
                                                                            NULL_PLUGIN_PROPERTIES, 
                                                                            requestOptions);
payment_method      = KillBillClient::Model::PaymentMethod

account_id = "faf239a5-456a-4eb9-aef9-8d2254ef57dc"
with_plugin_info = false

accountPaymentMethods  = payment_method.find_all_by_account_id( account_id, 
                                                                with_plugin_info,
                                                                options)
accountApi = killbill.AccountApi()

account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountPaymentMethods = accountApi.get_payment_methods_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

const response: AxiosResponse<killbill.PaymentMethod[], any> = await api.getPaymentMethodsForAccount(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

$accountPaymentMethods = $apiInstance-> getPaymentMethodsForAccount($accountID);

Example Response:

[
  {
    "paymentMethodId": "f835c556-0694-4883-b4c1-d1b6e308409b",
    "externalKey": "unknown",
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "isDefault": false,
    "pluginName": "__EXTERNAL_PAYMENT__",
    "pluginInfo": null,
    "auditLogs": []
  }
]

Request Body

The request body is a JSON string representing any plugin specific payment information (payment token for exampe).

Query Parameters

Name Type Required Default Description
withPluginInfo boolean false false Choose true to include plugin info.
includedDeleted boolean false false Choose true to include deleted payment methods
pluginProperty array of strings false empty list list of plugin properties, if any
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a list of payment method objects.

Set the default payment method

This API sets an existing payment method to be the default payment method.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods/{paymentMethodId}/setDefault

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 "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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods/f835c556-0694-4883-b4c1-d1b6e308409b/setDefault"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
UUID paymentMethodId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.setDefaultPaymentMethod(accountId, 
                                   paymentMethodId, 
                                   NULL_PLUGIN_PROPERTIES, 
                                   requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

payment_method = KillBillClient::Model::PaymentMethod

account_id = 'faf239a5-456a-4eb9-aef9-8d2254ef57dc'
payment_method_id = 'faf239a5-456a-4eb9-aef9-8d2254ef57dc'

payment_method.set_default( payment_method_id,
                            account_id,
                            user,
                            reason,
                            comment,
                            options)
accountApi = killbill.AccountApi()

account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'
payment_method_id = '4f124c0d-cee7-49b1-a181-3b0738c685d7'

accountApi.set_default_payment_method(account_id, 
                                      payment_method_id, 
                                      created_by='demo',
                                      reason='reason', 
                                      comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

const paymentMethodId = '4f124c0d-cee7-49b1-a181-3b0738c685d7';

api.setDefaultPaymentMethod(accountID,paymentMethodId,'created_by');
$apiInstance = $client->getAccountApi();

$xKillbillCreatedBy = "user";

$paymentMethodID = "4f124c0d-cee7-49b1-a181-3b0738c685d7";
$accountID = "88a5987a-1e1c-47c5-ba95-34ef14db3d46";

$apiInstance-> setDefaultPaymentMethod($accountID,$paymentMethodID,$xKillbillCreatedBy);

Query Parameters

Name Type Required Default Description
payAllUnpaidInvoices boolean false false Choose true to pay all unpaid invoices
pluginProperty array of strings false empty list List of plugin properties, if any

Response

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

Refresh account payment methods

This endpoint is for a rare use case where information for a particular payment method is stored inside the third party gateway, and both Kill Bill core and its payment plugin need to have their view updated.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods/refresh

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 "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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods/refresh"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
String pluginName = "__EXTERNAL_PAYMENT__";
Map<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.refreshPaymentMethods(accountId, 
                                 pluginName, 
                                 NULL_PLUGIN_PROPERTIES, 
                                 requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

payment_method = KillBillClient::Model::PaymentMethod

account_id = "faf239a5-456a-4eb9-aef9-8d2254ef57dc"

payment_method.refresh( account_id, 
                        user, 
                        reason, 
                        comment, 
                        options)
accountApi = killbill.AccountApi()

account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountApi.refresh_payment_methods(account_id,
                                   created_by='demo',
                                   reason='reason', 
                                   comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

api.refreshPaymentMethods(accountID,'created_by');
$apiInstance = $client->getAccountApi();

$xKillbillCreatedBy = "user";

$accountID = "88a5987a-1e1c-47c5-ba95-34ef14db3d46";

$apiInstance-> refreshPaymentMethods($accountID,$xKillbillCreatedBy);

Query Parameters

Name Type Required Default Description
PluginName array of strings false empty list List of plugins, if any
pluginProperty array of strings false empty list List of plugin properties, if any

Response

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

Overdue

The system can be configured to move an Account through various overdue (a.k.a. dunning) states when invoices are left unpaid.

Retrieve overdue state for account

Retrieve the current overdue/dunning state for an Account.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/overdue

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/overdue"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("d3a82897-ae72-4a2e-9bca-e3c1fe087f84");

OverdueState result = accountApi.getOverdueAccount(accountId, requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'd3a82897-ae72-4a2e-9bca-e3c1fe087f84'

accountOverdueState = account.overdue(options)
accountApi = killbill.AccountApi()

account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountOverdueState = accountApi.get_overdue_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

const response: AxiosResponse<killbill.OverdueState, any> = await api.getOverdueAccount(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

$accountOverdueState = $apiInstance-> getOverdueAccount($accountID);

Example Response:

{
  "name": "__KILLBILL__CLEAR__OVERDUE_STATE__",
  "externalMessage": "",
  "daysBetweenPaymentRetries": [
    8,
    8,
    8
  ],
  "isDisableEntitlementAndChangesBlocked": false,
  "isBlockChanges": false,
  "isClearState": true,
  "reevaluationIntervalDays": null
}

Query Parameters

None.

Returns

If successful, returns a status code of 200 and an overdue state object.

Blocking State

As part of the entitlement features, Kill Bill provides an abstraction to include BlockingState events into the per Account event stream. The main idea is to allow billing to be modified, such as by pausing a specific subscription or all subscriptions, and to allow modification of the entitlement state, such as by disabling the service associated with a given subscription. The entitlement internal documentation provides some overview of the mechanism. Blocking states are mostly manipulated from inside Kill Bill core, but the functionality is exposed through the API, with the caveat that it is an advanced feature and can lead to unintented behavior if not used properly.

Note that the term BlockingState seems to indicate that something will be blocked, and this can certainly be the case, but not necessarily; actually the attributes isBlockChange, isBlockEntitlement, isBlockBilling will drive this behavior. These flags are always considered on a per blocking state service, regardless of the state name. For instance, consider the following two scenarios:

In Scenario 1, billing is blocked between T1 and T2, while entitlement is blocked between T2 and T3. In Scenario 2 however, billing is blocked between T1 and T3, while entitlement is blocked between T2 and T4.

Blocking State Resource

A Blocking State Resource represents a blocking state. It has the following attributes:

Name Type Generated by Description
blockedId string system UUID for this blocking state id
stateName string user Name of the blocking state
service string user Name of the service that inserts the blocking state
isBlockChange boolean user Boolean flag that indicates whether changes should be blocked
isBlockEntitlement boolean user Boolean flag that indicates whether the entitlement should be blocked
isBlockBilling boolean user Boolean flag that indicates whether billing should be blocked
effectiveDate DateTime user DateTime that the change should be effective
type string user Type of blocking state. Possible values are SUBSCRIPTION, SUBSCRIPTION_BUNDLE and ACCOUNT

Block an account

Add a BlockingState event for this account.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/block

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 '{ "stateName": "STATE1", "service": "ServiceStateService", "isBlockChange": false, "isBlockEntitlement": false, "isBlockBilling": false }' \
    "http://127.0.0.1:8080/1.0/kb/accounts/10483c3a-3394-4667-8519-0d849e9a8ec2/block"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

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

BlockingState blockingState = new BlockingState();
blockingState.setStateName("STATE1");
blockingState.setService("ServiceStateService");
blockingState.setIsBlockChange(false);
blockingState.setIsBlockBilling(false);
blockingState.setIsBlockEntitlement(false);

LocalDate requestedDate = new LocalDate("2013-08-01");
Map<String, String> pluginProperty = Collections.emptyMap();

BlockingStates result = accountApi.addAccountBlockingState(accountId,
                                                           blockingState,
                                                           requestedDate,
                                                           pluginProperty,
                                                           requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = '864c1418-e768-4cd5-a0db-67537144b685'

state_name = "STATE1"
service = "ServiceStateService"
block_change = false
block_entitlement = false
block_billing = false
requested_date = "2013-08-01"

account.set_blocking_state(state_name,
                           service,
                           block_change, 
                           block_entitlement,
                           block_billing, 
                           requested_date,
                           user, 
                           reason, 
                           comment,
                           options)
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
body = BlockingState(state_name='STATE1',
                     service='ServiceStateService',
                     is_block_change=False,
                     is_block_entitlement=False,
                     is_block_billing=False)

accountApi.add_account_blocking_state(account_id, 
                                      body, 
                                      created_by='demo',
                                      reason='reason', 
                                      comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.BlockingState = {  stateName: 'ACCT_PAUSED',
                        service: 'billing',
                        isBlockChange: false,
                        isBlockEntitlement: false,
                        isBlockBilling: false
                      }

api.addAccountBlockingState(body,'07c0cef4-41c5-4606-b2cd-661332cdd41c','created_by');
$apiInstance = $client->getAccountApi();

$xKillbillCreatedBy = "user";

$blockingState = new  BlockingState();
$blockingState->setStateName('ACCT_PAUSED');
$blockingState->setService('billing');
$blockingState->setIsBlockChange('false');
$blockingState->setIsBlockBilling('false');
$blockingState->setIsBlockEntitlement('false');

$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";

$apiInstance-> addAccountBlockingState($blockingState,$xKillbillCreatedBy,$accountID);

Request Body

A JSON string representing the blocking state object to be added. For details on this resource see blocking state.

Query Parameters

Name Type Required Default Description
requestedDate string false block immediately Date/DateTime to block an account in yyyy-mm-dd/yyyy-mm-ddThh:mm format.
pluginProperty array of strings false empty list List of plugin properties, if any

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for retrieving blocking states for the account.

Retrieve blocking states for account

Retrieves the BlockingState associated with a given resource. BlockingState can be set at the Account, Bundle or Subscription level.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/block

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/accounts/10483c3a-3394-4667-8519-0d849e9a8ec2/block?blockingStateTypes=ACCOUNT"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");

List<BlockingStateType> blockingStateTypes = List.of(BlockingStateType.SUBSCRIPTION_BUNDLE);
List<String> blockingStateSvcs = List.of("service");

BlockingStates blockingStates = accountApi.getBlockingStates(accountId, 
                                                             blockingStateTypes, 
                                                             blockingStateSvcs, 
                                                             AuditLevel.FULL, 
                                                             requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'ee6835f0-8347-42d3-958c-9a939383ba28'

blocking_state_types = 'ACCOUNT'
blocking_state_svcs = nil
audit = 'NONE'

accountBlockingStates = account.blocking_states(blocking_state_types,
                                                blocking_state_svcs, 
                                                audit,
                                                options)
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountBlockingStates = accountApi.get_blocking_states(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

const response: AxiosResponse<killbill.BlockingState[], any> = await api.getBlockingStates(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

$accountBlockingStates = $apiInstance-> getBlockingStates($accountID);

Example Response:

[
  {
    "blockedId": "10483c3a-3394-4667-8519-0d849e9a8ec2",
    "stateName": "STATE1",
    "service": "ServiceStateService",
    "isBlockChange": false,
    "isBlockEntitlement": false,
    "isBlockBilling": false,
    "effectiveDate": "2018-07-18T14:45:37.000Z",
    "type": "ACCOUNT",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
blockingStateTypes array of strings false retrieve all blocking state types to retrieve: "SUBSCRIPTION", "SUBSCRIPTION_BUNDLE", "ACCOUNT"
blockingStateSvcs array of strings false retrieve all filter list for blocking state services
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a blocking state object.

Hierarchical Accounts

When using the hierarchical account feature, this API allows you to retrieve all the child Accounts for a given parent Account.

List child accounts

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/children

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/children"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID parentAccountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");
Boolean accountWithBalance = true; // Will include account balance
Boolean accountWithBalanceAndCBA = true; // Will include account balance and CBA info

Accounts childrenAccounts = accountApi.getChildrenAccounts(parentAccountId, 
                                                           accountWithBalance, 
                                                           accountWithBalanceAndCBA, 
                                                           AuditLevel.NONE, 
                                                           requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = "ee6835f0-8347-42d3-958c-9a939383ba28"

with_balance = false
with_balance_and_cba = false
audit = 'NONE'

childrenAccounts = account.children( with_balance, 
                                     with_balance_and_cba, 
                                     audit, 
                                     options)
accountApi = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

childrenAccounts = accountApi.get_children_accounts(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

const response: AxiosResponse<killbill.Account[], any> = await api.getChildrenAccounts(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

$childAccounts = $apiInstance-> getChildrenAccounts($accountID);

Example Response:

[
   {
      "accountId":"e19c6ab3-1a21-42f2-8ea2-9859c082b093",
      "name":"John Doe",
      "externalKey":"1522172592-516014",
      "email":"John@laposte.com",
      "billCycleDayLocal":0,
      "currency":"USD",
      "parentAccountId":"01ab962b-3c66-4b17-b391-ffcc9fe51884",
      "isPaymentDelegatedToParent":true,
      "timeZone":"UTC",
      "address1":"7, yoyo road",
      "address2":"Apt 5",
      "postalCode":"94105",
      "company":"Unemployed",
      "city":"San Francisco",
      "state":"California",
      "country":"US",
      "locale":"fr_FR",
      "auditLogs":[]
   }
]

Query Parameters

Name Type Required Default Description
accountWithBalance boolean false false if true, returns accountBalance info
accountWithBalanceAndCBA boolean false false if true, returns accountBalance and accountCBA info
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a list of child account objects.

Transfer a given child credit to the parent level

In the context of the Hierarchical Account feature, this allows moving the potential child credit to the parent level.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/accounts/{childAccountId}/transferCredit

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 "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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/transferCredit"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID childAccountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");

accountApi.transferChildCreditToParent(childAccountId, requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'

account.transfer_child_credit(user,
                              reason,
                              comment,
                              options)
accountApi = killbill.AccountApi()

child_account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountApi.transfer_child_credit_to_parent(child_account_id,
                                           created_by='demo',
                                           reason='reason', 
                                           comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const childAccountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

api.transferChildCreditToParent(childAccountID, 'created_by');
$apiInstance = $client->getAccountApi();

$childAccountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';

$apiInstance-> transferChildCreditToParent($childAccountID,$xKillbillCreatedBy);

Query Parameters

None.

Response

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

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resource. In particular they can be added to the customer Account. For details on Custom Fields see Custom Field.

Add custom fields to account

Add custom fields to a given Account.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields

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 '[ { "objectType": "ACCOUNT", "name": "Test Custom Field", "value": "demo_test_value" }]' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("15434b45-54c1-4a44-851c-b1f2f7a52f03");
final List<AuditLog> EMPTY_AUDIT_LOGS = Collections.emptyList();

CustomFields customFields = new CustomFields();
customFields.add(new CustomField(null, 
                                 accountId,
                                 ObjectType.ACCOUNT,
                                 "Test Custom Field", 
                                 "test_value", 
                                 EMPTY_AUDIT_LOGS));

accountApi.createAccountCustomFields(accountId, 
                                     customFields, 
                                     requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = '15434b45-54c1-4a44-851c-b1f2f7a52f03'

custom_field = KillBillClient::Model::CustomFieldAttributes.new

custom_field.object_type = 'ACCOUNT'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

account.add_custom_field(custom_field, 
                         user,
                         reason,
                         comment,
                         options)
accountApi = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
body = CustomField(name='Test Custom Field', value='test_value')

accountApi.create_account_custom_fields(account_id,
                                        [body],
                                        created_by='demo',
                                        reason='reason', 
                                        comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.CustomField[] = [{ name: 'Test Custom Field', value: 'test_value' }];

api.createAccountCustomFields(body,'8992e146-bfa1-4126-a045-98b844a4adcb','created_by');
$apiInstance = $client->getAccountApi();

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


$customField = new CustomField();

$customField->setName("Test Custom Field");
$customField->setValue("test_value");

$customFields = array($customField);

$accountID = "8992e146-bfa1-4126-a045-98b844a4adcb";

$apiInstance->createAccountCustomFields($customFields,$xKillbillCreatedBy, $accountID, $xKillbillReason,$xKillbillComment);

Request Body

A list of objects giving the name and value of the custom field, or fields, to be added. For example:

[ { "name": "CF1", "value": "123" } ]

Query Parameters

None.

Response

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL to retrieve the custom fields associated with the account.

Retrieve all custom fields

Retrieves all custom fields attached to various resources owned by the Account. This endpoint allows you to retrieve all custom fields, or to filter them by type, e.g Subscription.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/allCustomFields

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/allCustomFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("b38de59f-7dd0-447a-a508-9b022b808250");

CustomFields allAccountCustomFields = accountApi.getAllCustomFields(accountId, 
                                                                    ObjectType.ACCOUNT, 
                                                                    AuditLevel.FULL, 
                                                                    requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

object_type = 'ACCOUNT'
audit = 'NONE'

allCustomFields = account.all_custom_fields(object_type,
                                            audit, 
                                            options)
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

allCustomFields = accountApi.get_all_custom_fields(account_id,object_type='ACCOUNT')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

const response: AxiosResponse<killbill.CustomField[], any> = await api.getAllCustomFields(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";

$allCustomFields = $apiInstance->getAllCustomFields($accountID);

Example Response:

[
  {
    "customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "objectType": "ACCOUNT",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
objectType string false retrieve all type of object
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Possible values for objectType are ACCOUNT, ACCOUNT_EMAIL, BLOCKING_STATES, BUNDLE, CUSTOM_FIELD, INVOICE, PAYMENT, TRANSACTION, INVOICE_ITEM, INVOICE_PAYMENT, SUBSCRIPTION, SUBSCRIPTION_EVENT, SERVICE_BROADCAST, PAYMENT_ATTEMPT, PAYMENT_METHOD, TAG, TAG_DEFINITION, TENANT, or TENANT_KVS.

Response

If successful, returns a status code of 200 and a list of custom field objects

Retrieve account custom fields

Retrieve the custom fields associated with an account

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"   
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");

List<CustomField> accountCustomFields = accountApi.getAccountCustomFields(accountId,
                                                                          AuditLevel.NONE, 
                                                                          requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '59860a0d-c032-456d-a35e-3a48fe8579e5'

audit = 'NONE'

accountCustomFields = account.custom_fields(audit, options)
accountApi = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountCustomFields = accountApi.get_account_custom_fields(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

const response: AxiosResponse<killbill.CustomField[], any> = await api.getCustomFields(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";

$accountCustomFields = $apiInstance->getAccountCustomFields($accountID);

Example Response:

[
  {
    "customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "objectType": "ACCOUNT",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a (possibly empty) list of custom field objects

Modify custom fields for an account

Modify the custom fields associated with an account. Note that it is not possible to modify the name of a custom field, it is only possible to modify its value.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields

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 "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '[ { "customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe", "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "objectType": "ACCOUNT", "name": "Test Custom Field" , "value": "test_modify_value", "auditLogs": [] }]' \
    "http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

CustomField customFieldModified = new CustomField();
customFieldModified.setCustomFieldId(customFieldsId);
customFieldModified.setValue("NewValue");
CustomFields customFields = new CustomFields();
customFields.add(customFieldModified);

accountApi.modifyAccountCustomFields(accountId, 
                                     customFields, 
                                     requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '59860a0d-c032-456d-a35e-3a48fe8579e5'

custom_field = KillBillClient::Model::CustomFieldAttributes.new

custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
custom_field.name = 'Test Modify'
custom_field.value = 'test_modify_value'

account.modify_custom_field(custom_field,                                       
                            user, 
                            reason,
                            comment, 
                            options)
account = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
body = CustomField(custom_field_id=custom_field_id, 
                   name='Test Custom Field', 
                   value='test_value')

account.modify_account_custom_fields(account_id, 
                                     [body], 
                                     created_by='demo',
                                     reason='reason', 
                                     comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const body: killbill.CustomField = { name: 'Test Custom Field', value: 'test_modify_value' };

api.modifyAccountCustomFields(body,'59860a0d-c032-456d-a35e-3a48fe8579e5','created_by')
$apiInstance = $client->getAccountApi();

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


$customField = new CustomField();

$customField->setCustomFieldId('92b90b52-d4ef-47e7-ba4e-614255353a9a');
$customField->setValue("test_modify_value");

$customFields = array($customField);

$accountID = "59860a0d-c032-456d-a35e-3a48fe8579e5";

$apiInstance->modifyAccountCustomFields($customFields,$xKillbillCreatedBy, $accountID, $xKillbillReason,$xKillbillComment);

Request Body

A list of objects specifying the id and the new value for the custom fields to be modified. For example:

[ { "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f", "value": "123" } ]

Although the fieldName and objectType can be specified in the request body, these cannot be modified, only the field value can be modified.

Query Parameters

None.

Returns

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

Remove custom fields from account

Remove a specified set of custom fields from the account

HTTP Request

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields?customField=9913e0f6-b5ef-498b-ac47-60e1626eba8f"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = List.of(customFieldsId);
accountApi.deleteAccountCustomFields(accountId, 
                                     customFieldsList, 
                                     requestOptions);
custom_field_id = custom_field.custom_field_id

account.remove_custom_field(custom_field_id, 
                            user, 
                            reason,
                            comment, 
                            options)
account = killbill.AccountApi()

account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

account.delete_account_custom_fields(account_id,
                                     created_by='demo',
                                     reason='reason', 
                                     comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';

api.deleteAccountCustomFields(accountID,'created_by')
$apiInstance = $client->getAccountApi();

$xKillbillCreatedBy = "user";

$customField = new CustomField();

$accountID = "8992e146-bfa1-4126-a045-98b844a4adcb";

$apiInstance->deleteAccountCustomFields($accountID,$xKillbillCreatedBy);

Query Parameters

Name Type Required Default Description
customField string true none Custom field object ID that should be deleted. Multiple custom fields can be deleted by specifying a separate customField parameter corresponding to each field

Response

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

Tags

This section provides APIs to add tags, to retrieve all tags, to retrieve account tags and to remove tags associated with the account. For more details on tags, see section Tag.

Add tags to account

This API adds one or more tags to an account. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/tags

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 '[ "00000000-0000-0000-0000-000000000002"]' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("f4087a76-9f8a-4893-abbf-c5bb69975d1b");

UUID autoPayOffTagId = UUID.fromString("00000000-0000-0000-0000-000000000001");

Tags result = accountApi.createAccountTags(accountId, 
                                           List.of(autoPayOffTagId), 
                                           requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = 'f4087a76-9f8a-4893-abbf-c5bb69975d1b'

tag_name = 'TEST'

account.add_tag(tag_name,
                user,
                reason,
                comment,
                options)
accountApi = killbill.AccountApi()

account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tagDefIds = ["00000000-0000-0000-0000-000000000002"]

accountApi.create_account_tags(account_id, 
                               tagDefIds, 
                               created_by='demo',
                               reason='reason', 
                               comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const tags = ['00000000-0000-0000-0000-000000000002'];

api.createAccountTags(tags,'b0da8392-49ba-43f2-8fac-3f9f85b8ff61','created_by')
$apiInstance = $client->getAccountApi();

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

$tags = ['00000000-0000-0000-0000-000000000002'];

$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";

$apiInstance->createAccountTags($tags,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);

Request Body

A JSON array containing one or more tag definition ids to be added as user tags.

Query Parameters

None.

Returns

If successful, returns a 201 status code. In addition, a Location header is returned giving the URL to retrieve the tags associated with the account.

Retrieve all tags

Retrieves all tags attached to resources owned by this Account. This API allows you to retrieve all tags, or only tags attached to a specified resource type.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/allTags

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/allTags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");

Tags allAccountTags = accountApi.getAllTags(accountId,
                                            ObjectType.ACCOUNT,
                                            requestOptions);
accountApi = killbill.AccountApi()

account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

allAccountTags = accountApi.get_all_tags(account_id)
account = KillBillClient::Model::Account.new

account.account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

object_type = 'ACCOUNT'
included_deleted = false
audit = 'NONE'

allTags = account.all_tags(object_type, 
                           included_deleted, 
                           audit, 
                           options)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';

const response: AxiosResponse<any> = await api.getAllTags(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";

$allTags = $apiInstance->getAllTags($accountID);

Example Response:

[
  {
    "tagId": "0f7c5837-1ed9-41ab-b391-9ef7ea4ab049",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "tagDefinitionId": "00000000-0000-0000-0000-000000000002",
    "tagDefinitionName": "AUTO_INVOICING_OFF",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
objectType string false all object types choose type of object
includedDeleted boolean false false choose true to include deleted tags
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Possible values for objectType are ACCOUNT, ACCOUNT_EMAIL, BLOCKING_STATES, BUNDLE, CUSTOM_FIELD, INVOICE, PAYMENT, TRANSACTION, INVOICE_ITEM, INVOICE_PAYMENT, SUBSCRIPTION, SUBSCRIPTION_EVENT, SERVICE_BROADCAST, PAYMENT_ATTEMPT, PAYMENT_METHOD, TAG, TAG_DEFINITION, TENANT, or TENANT_KVS.

Response

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

Retrieve account tags

Retrieve all tags attached to this account itself.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/tags

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");
Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags1 = accountApi.getAccountTags(accountId, 
                                            includedDeleted, 
                                            AuditLevel.FULL, 
                                            requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'

included_deleted = false
audit = 'NONE'

accountTags = account.tags(included_deleted,
                           audit,
                           options)
accountApi = killbill.AccountApi()

account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'

accountTags = accountApi.get_account_tags(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

const response: AxiosResponse<any> = await api.getAccountTags(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";

$accountTags = $apiInstance->getAccountTags($accountID);

Example Response:

[
  {
    "tagId": "0f7c5837-1ed9-41ab-b391-9ef7ea4ab049",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "tagDefinitionId": "00000000-0000-0000-0000-000000000002",
    "tagDefinitionName": "AUTO_INVOICING_OFF",
    "auditLogs": []
  }
]

Query Parameters

Name Type Required Default Description
includedDeleted boolean false false choose true to include deleted tags
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

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

Remove tags from account

This API removes a list of tags attached to an account.

HTTP Request

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags?tagDef=00000000-0000-0000-0000-000000000002"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");
UUID autoPayOffId = UUID.fromString("00000000-0000-0000-0000-000000000001");

accountApi.deleteAccountTags(accountId, 
                             List.of(autoPayOffId), 
                             requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'

account = KillBillClient::Model::Account.new

account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'

tag_name = 'TEST'

account.remove_tag(tag_name,
                   user,
                   reason,
                   comment,
                   options)
accountApi = killbill.AccountApi()

account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tagDefIds = ["00000000-0000-0000-0000-000000000002"]

accountApi.delete_account_tags(account_id, 
                               tag_def=tagDefIds,
                               created_by='demo',
                               reason='reason', 
                               comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

api.deleteAccountTags(accountID,'created_by');
$apiInstance = $client->getAccountApi();

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

$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";

$apiInstance->deleteAccountTags($accountID,$xKillbillCreatedBy,$xKillbillCreatedBy,$xKillbillComment);

Query Parameters

Name Type Required Default Description
tagDef array of string true none A tag definition ID identifying the tag that should be removed. Multiple tags can be deleted by specifying a separate tagDef parameter corresponding to each tag.

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 audit logs

Retrieve a list of audit log records showing events that occurred involving changes to any resource associated with the specified account. History information (a copy of the full resource object) is not included.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/auditLogs

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/auditLogs"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("e9432491-6558-4007-85ef-cdae171d240c");

AuditLogs auditLogsJson = accountApi.getAccountAuditLogs(accountId, 
                                                         requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = '4e4d8acd-c97d-447a-814b-28f995a9106c'

auditLogs = account.audit(options)
accountApi = killbill.AccountApi()

account_id = '4e4d8acd-c97d-447a-814b-28f995a9106c'

auditLogs = accountApi.get_account_audit_logs(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountAuditLogs(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";

$accountAuditLogs = $apiInstance->getAccountAuditLogs($accountID);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-17T15:02:45.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "bca75b40-ffa3-41f8-9fde-06f83ee303e8",
    "history": null
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-17T18:46:47.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "9a61a1e6-78f3-43d3-addf-e7ada180b23d",
    "history": null
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-17T18:48:37.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "0c41a04d-4037-4fa9-af71-dfe54af4d3ae",
    "history": null
  },
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-17T19:07:25.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "c9b9ab11-14b1-41b5-8371-1c425f273336",
    "history": null
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-17T19:26:46.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "fd26b216-deb2-43d4-b748-dec8e9917ada",
    "history": null
  },
  {
    "changeType": "DELETE",
    "changeDate": "2018-07-17T20:02:01.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "0d5c8db7-974f-47e0-9332-5d9625f72155",
    "history": null
  }
]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of audit logs.

Retrieve account audit logs with history

Retrieve a list of audit log records showing events that occurred involving changes to the specified account itself. History information (a copy of the full account object) is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/auditLogsWithHistory

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("ecbff3be-3cbf-4e1d-ae05-d323d4597877");

List<AuditLog> auditLogWithHistories = accountApi.getAccountAuditLogsWithHistory(accountId, 
                                                                                 requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

auditLogsWithHistory = account.audit_logs_with_history(options)
accountApi = killbill.AccountApi()

account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

auditLogsWithHistory = accountApi.get_account_audit_logs_with_history(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountAuditLogsWithHistory(accountID);
$apiInstance = $client->getAccountApi();

$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";

$accountAuditLogs = $apiInstance->getAccountAuditLogsWithHistory($accountID);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-17T15:02:45.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "bca75b40-ffa3-41f8-9fde-06f83ee303e8",
    "history": {
      "id": null,
      "createdDate": "2018-07-17T15:02:45.000Z",
      "updatedDate": "2018-07-17T15:02:45.000Z",
      "recordId": 120,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "email": "john@laposte.com",
      "name": "John Doe",
      "firstNameLength": null,
      "currency": "USD",
      "parentAccountId": null,
      "isPaymentDelegatedToParent": null,
      "billingCycleDayLocal": 0,
      "paymentMethodId": null,
      "referenceTime": "2018-07-17T15:02:45.000Z",
      "timeZone": "UTC",
      "locale": null,
      "address1": null,
      "address2": null,
      "companyName": null,
      "city": null,
      "stateOrProvince": null,
      "country": null,
      "postalCode": null,
      "phone": null,
      "notes": null,
      "migrated": null,
      "tableName": "ACCOUNT",
      "historyTableName": "ACCOUNT_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-17T18:46:47.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "9a61a1e6-78f3-43d3-addf-e7ada180b23d",
    "history": {
      "id": null,
      "createdDate": "2018-07-17T18:46:47.000Z",
      "updatedDate": "2018-07-17T18:46:47.000Z",
      "recordId": 120,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "email": "john@laposte.com",
      "name": "Another Name",
      "firstNameLength": null,
      "currency": "USD",
      "parentAccountId": null,
      "isPaymentDelegatedToParent": false,
      "billingCycleDayLocal": 0,
      "paymentMethodId": null,
      "referenceTime": "2018-07-17T15:02:45.000Z",
      "timeZone": "UTC",
      "locale": null,
      "address1": null,
      "address2": null,
      "companyName": null,
      "city": null,
      "stateOrProvince": null,
      "country": null,
      "postalCode": null,
      "phone": null,
      "notes": null,
      "migrated": null,
      "tableName": "ACCOUNT",
      "historyTableName": "ACCOUNT_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-17T18:48:37.000Z",
    "objectType": "ACCOUNT",
    "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "0c41a04d-4037-4fa9-af71-dfe54af4d3ae",
    "history": {
      "id": null,
      "createdDate": "2018-07-17T18:48:37.000Z",
      "updatedDate": "2018-07-17T18:48:37.000Z",
      "recordId": 120,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "email": "john@laposte.com",
      "name": "John Doe",
      "firstNameLength": null,
      "currency": "USD",
      "parentAccountId": null,
      "isPaymentDelegatedToParent": false,
      "billingCycleDayLocal": 0,
      "paymentMethodId": null,
      "referenceTime": "2018-07-17T15:02:45.000Z",
      "timeZone": "UTC",
      "locale": null,
      "address1": null,
      "address2": null,
      "companyName": null,
      "city": null,
      "stateOrProvince": null,
      "country": null,
      "postalCode": null,
      "phone": null,
      "notes": null,
      "migrated": null,
      "tableName": "ACCOUNT",
      "historyTableName": "ACCOUNT_HISTORY"
    }
  }
]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of audit logs.

Retrieve account email audit logs with history

Retrieve a list of audit log records showing events that occurred involving changes to a specified account email. History information (a copy of the full email object) is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails/{accountEmailId}/auditLogsWithHistory

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails/aa2a5614-88d9-4ec3-a042-a4771bd66670/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("873c26ef-a3fa-4942-b2f5-549b51f20b1a");
UUID accountEmailId = UUID.fromString("f637441d-855e-4bf5-bac1-6426bdb116d6");

List<AuditLog> result = accountApi.getAccountEmailAuditLogsWithHistory(accountId, 
                                                                       accountEmailId, 
                                                                       requestOptions);
account = KillBillClient::Model::Account.new

account.account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

account_email_id = 'a4627e89-a73b-4167-a7ba-92a2881eb3c4'

emailAuditLogsWithHistory = account.email_audit_logs_with_history(account_email_id, options)
accountApi = killbill.AccountApi()

account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
account_email_id = 'bb390282-6757-4f4f-8dd5-456abd9f30b2'

emailAuditLogsWithHistory = accountApi.get_account_email_audit_logs_with_history(account_id,
                                                     account_email_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda';

const accountEmailID = 'bb390282-6757-4f4f-8dd5-456abd9f30b2';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountEmailAuditLogsWithHistory(accountID,accountEmailID);
$apiInstance = $client->getAccountApi();

$accountID = "c62d5f6d-0b57-444d-bf9b-dd23e781fbda";
$accountEmailID = 'bb390282-6757-4f4f-8dd5-456abd9f30b2';

$accountEmailAuditLogs = $apiInstance->getAccountEmailAuditLogsWithHistory($accountID,$accountEmailID);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-18T15:13:22.000Z",
    "objectType": "ACCOUNT_EMAIL",
    "objectId": "aa2a5614-88d9-4ec3-a042-a4771bd66670",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "927546eb-3431-4bcf-8fcc-1787d2130772",
    "history": {
      "id": null,
      "createdDate": "2018-07-18T15:13:22.000Z",
      "updatedDate": "2018-07-18T15:13:22.000Z",
      "recordId": 1,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "email": "email@laposte.com",
      "isActive": true,
      "tableName": "ACCOUNT_EMAIL",
      "historyTableName": "ACCOUNT_EMAIL_HISTORY"
    }
  }
]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of account email audit records, including history (copies of the complete record).

Retrieve blocking state audit logs with history

Retrieves the audit logs for a specific blocking state, given the blocking state id. History records (blocking state objects) are included.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/block/{blockingId}/auditLogsWithHistory

See section Account Blocking State for an introduction to blocking states.

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/accounts/block/763fd113-1b9b-4d0d-be01-6ee56d3879f5/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID blockingId = UUID.fromString("0997b953-2b3a-4dc5-ad01-c38911662923");
AuditLogs result = accountApi.getBlockingStateAuditLogsWithHistory(blockingId, requestOptions);
const api: killbill.AccountApi = new killbill.AccountApi(config);

const blockingId = '0997b953-2b3a-4dc5-ad01-c38911662923';

const response: AxiosResponse<killbill.AuditLog[], any> = await api.getBlockingStateAuditLogsWithHistory(blockingId);
$apiInstance = $client->getAccountApi();

$blockingId = '0997b953-2b3a-4dc5-ad01-c38911662923';

$blockingStateAuditLogs = $apiInstance->getBlockingStateAuditLogsWithHistory($blockingId);

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "BLOCKING_STATES",
    "objectId": "763fd113-1b9b-4d0d-be01-6ee56d3879f5",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": "2019-02-22T22:38:10.000Z",
      "recordId": 1326,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "blockableId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
      "type": "SUBSCRIPTION",
      "state": "ENT_STARTED",
      "service": "entitlement-service",
      "blockChange": false,
      "blockEntitlement": false,
      "blockBilling": false,
      "effectiveDate": "2019-02-22T22:38:10.000Z",
      "isActive": true,
      "tableName": "BLOCKING_STATES",
      "historyTableName": "BLOCKING_STATES",
      "active": true
    }
  }
]

Query Parameters

None.

Response

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

Retrieve account timeline

This API retrieves the chronological set of events that occurred concerning a specific Account.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/timeline

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/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/timeline"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

UUID accountId = UUID.fromString("16364ac4-2a77-4444-b2d8-e980c37a8954");
Boolean parallel = false;

AccountTimeline timeline = accountApi.getAccountTimeline(accountId,
                                              parallel,
                                              AuditLevel.NONE,
                                              requestOptions);
account_id = account.account_id
audit = 'MINIMAL'

KillBillClient::Model::AccountTimeline.timeline(account_id,
                                                audit,
                                                options)
accountApi = killbill.AccountApi()

account_id = '43488882-1777-460c-bc32-e375e67d09cf'

accountTimeline = accountApi.get_account_timeline(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);

const accountID = '43488882-1777-460c-bc32-e375e67d09cf';

const response: AxiosResponse<killbill.AccountTimeline, any> = await api.getAccountTimeline(accountID);
$apiInstance = $client->getAccountApi();

$accountID = '43488882-1777-460c-bc32-e375e67d09cf';

$accountTimeline = $apiInstance->getAccountTimeline($accountID);

Example Response:

{
  "account": {
    "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
    "name": "25thAuGCus6",
    "firstNameLength": null,
    "externalKey": "25thAuGCus6",
    "email": null,
    "billCycleDayLocal": 1,
    "currency": "USD",
    "parentAccountId": null,
    "isPaymentDelegatedToParent": false,
    "paymentMethodId": null,
    "referenceTime": "2023-08-25T16:28:43.000Z",
    "timeZone": "Etc/UTC",
    "address1": null,
    "address2": null,
    "postalCode": null,
    "company": null,
    "city": null,
    "state": null,
    "country": "US",
    "locale": "en_US",
    "phone": null,
    "notes": null,
    "isMigrated": false,
    "accountBalance": null,
    "accountCBA": null,
    "auditLogs": []
  },
  "bundles": [
    {
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "externalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "subscriptions": [
        {
          "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
          "bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
          "bundleExternalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
          "subscriptionId": "cc608e24-509e-4b99-9519-2eeef67c20a2",
          "externalKey": "cc608e24-509e-4b99-9519-2eeef67c20a2",
          "startDate": "2023-01-01T16:28:43.000Z",
          "productName": "prodA",
          "productCategory": "BASE",
          "billingPeriod": "MONTHLY",
          "phaseType": "EVERGREEN",
          "priceList": "DEFAULT",
          "planName": "Standard-monthly",
          "state": "ACTIVE",
          "sourceType": "NATIVE",
          "cancelledDate": null,
          "chargedThroughDate": "2023-09-01",
          "billingStartDate": "2023-01-01T16:28:43.000Z",
          "billingEndDate": null,
          "billCycleDayLocal": 1,
          "quantity": 1,
          "events": [
            {
              "eventId": "23088e1e-646c-4ce7-ad45-9c4369ef223a",
              "billingPeriod": "MONTHLY",
              "effectiveDate": "2023-01-01T16:28:43.000Z",
              "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
              "plan": "Standard-monthly",
              "product": "prodA",
              "priceList": "DEFAULT",
              "eventType": "START_ENTITLEMENT",
              "isBlockedBilling": false,
              "isBlockedEntitlement": false,
              "serviceName": "entitlement-service",
              "serviceStateName": "ENT_STARTED",
              "phase": "Standard-monthly-evergreen",
              "auditLogs": []
            },
            {
              "eventId": "1b122b2b-eea4-4a6b-80a2-f9ae2a336fad",
              "billingPeriod": "MONTHLY",
              "effectiveDate": "2023-01-01T16:28:43.000Z",
              "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
              "plan": "Standard-monthly",
              "product": "prodA",
              "priceList": "DEFAULT",
              "eventType": "START_BILLING",
              "isBlockedBilling": false,
              "isBlockedEntitlement": false,
              "serviceName": "billing-service",
              "serviceStateName": "START_BILLING",
              "phase": "Standard-monthly-evergreen",
              "auditLogs": []
            },
            {
              "eventId": "368581ee-cf14-4b81-9c34-c06adb5dbbcf",
              "billingPeriod": "MONTHLY",
              "effectiveDate": "2023-08-28T16:55:37.000Z",
              "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
              "plan": "Standard-monthly",
              "product": "prodA",
              "priceList": "DEFAULT",
              "eventType": "SERVICE_STATE_CHANGE",
              "isBlockedBilling": false,
              "isBlockedEntitlement": false,
              "serviceName": "ServiceStateService",
              "serviceStateName": "STATE1",
              "phase": "Standard-monthly-evergreen",
              "auditLogs": []
            }
          ],
          "priceOverrides": null,
          "prices": [
            {
              "planName": "Standard-monthly",
              "phaseName": "Standard-monthly-evergreen",
              "phaseType": "EVERGREEN",
              "fixedPrice": null,
              "recurringPrice": 100,
              "usagePrices": []
            }
          ],
          "auditLogs": []
        }
      ],
      "timeline": {
        "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
        "bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
        "externalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
        "events": [
          {
            "eventId": "23088e1e-646c-4ce7-ad45-9c4369ef223a",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2023-01-01T16:28:43.000Z",
            "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
            "plan": "Standard-monthly",
            "product": "prodA",
            "priceList": "DEFAULT",
            "eventType": "START_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_STARTED",
            "phase": "Standard-monthly-evergreen",
            "auditLogs": []
          },
          {
            "eventId": "1b122b2b-eea4-4a6b-80a2-f9ae2a336fad",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2023-01-01T16:28:43.000Z",
            "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
            "plan": "Standard-monthly",
            "product": "prodA",
            "priceList": "DEFAULT",
            "eventType": "START_BILLING",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "billing-service",
            "serviceStateName": "START_BILLING",
            "phase": "Standard-monthly-evergreen",
            "auditLogs": []
          },
          {
            "eventId": "368581ee-cf14-4b81-9c34-c06adb5dbbcf",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2023-08-28T16:55:37.000Z",
            "catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
            "plan": "Standard-monthly",
            "product": "prodA",
            "priceList": "DEFAULT",
            "eventType": "SERVICE_STATE_CHANGE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "ServiceStateService",
            "serviceStateName": "STATE1",
            "phase": "Standard-monthly-evergreen",
            "auditLogs": []
          }
        ],
        "auditLogs": []
      },
      "auditLogs": []
    }
  ],
  "invoices": [
    {
      "amount": 100,
      "currency": "USD",
      "status": "COMMITTED",
      "creditAdj": 0,
      "refundAdj": 0,
      "invoiceId": "2645c1f3-1d72-41a7-8cdb-3dca43340af6",
      "invoiceDate": "2023-08-25",
      "targetDate": "2023-01-01",
      "invoiceNumber": "17859",
      "balance": 0,
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "credits": [],
      "items": null,
      "trackingIds": null,
      "isParentInvoice": false,
      "parentInvoiceId": null,
      "parentAccountId": null,
      "auditLogs": []
    },
    {
      "amount": 100,
      "currency": "USD",
      "status": "COMMITTED",
      "creditAdj": 0,
      "refundAdj": 0,
      "invoiceId": "e8dbe200-0738-4317-9c74-581696a0b4e9",
      "invoiceDate": "2023-08-25",
      "targetDate": "2023-02-01",
      "invoiceNumber": "17860",
      "balance": 0,
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "credits": [],
      "items": null,
      "trackingIds": null,
      "isParentInvoice": false,
      "parentInvoiceId": null,
      "parentAccountId": null,
      "auditLogs": []
    },
    {
      "amount": 100,
      "currency": "USD",
      "status": "COMMITTED",
      "creditAdj": 0,
      "refundAdj": 0,
      "invoiceId": "72662545-787c-4e9a-90af-4ac728392c35",
      "invoiceDate": "2023-08-25",
      "targetDate": "2023-03-01",
      "invoiceNumber": "17861",
      "balance": 0,
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "credits": [],
      "items": null,
      "trackingIds": null,
      "isParentInvoice": false,
      "parentInvoiceId": null,
      "parentAccountId": null,
      "auditLogs": []
    },
    {
      "amount": 500,
      "currency": "USD",
      "status": "COMMITTED",
      "creditAdj": 0,
      "refundAdj": 0,
      "invoiceId": "3a5d2748-88df-4f3f-bb60-49e8fbce1c0a",
      "invoiceDate": "2023-08-25",
      "targetDate": "2023-08-25",
      "invoiceNumber": "17862",
      "balance": 0,
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
      "credits": [],
      "items": null,
      "trackingIds": null,
      "isParentInvoice": false,
      "parentInvoiceId": null,
      "parentAccountId": null,
      "auditLogs": []
    }
  ],
  "payments": [
    {
      "targetInvoiceId": "2645c1f3-1d72-41a7-8cdb-3dca43340af6",
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "paymentId": "555d80f8-abdf-4b25-9994-ac605b012ccb",
      "paymentNumber": "41",
      "paymentExternalKey": "555d80f8-abdf-4b25-9994-ac605b012ccb",
      "authAmount": 0,
      "capturedAmount": 0,
      "purchasedAmount": 100,
      "refundedAmount": 0,
      "creditedAmount": 0,
      "currency": "USD",
      "paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
      "transactions": [
        {
          "transactionId": "57857941-6956-413d-ac62-99af982d6f41",
          "transactionExternalKey": "57857941-6956-413d-ac62-99af982d6f41",
          "paymentId": "555d80f8-abdf-4b25-9994-ac605b012ccb",
          "paymentExternalKey": "555d80f8-abdf-4b25-9994-ac605b012ccb",
          "transactionType": "PURCHASE",
          "amount": 100,
          "currency": "USD",
          "effectiveDate": "2023-08-28T16:27:44.000Z",
          "processedAmount": 100,
          "processedCurrency": "USD",
          "status": "SUCCESS",
          "gatewayErrorCode": null,
          "gatewayErrorMsg": null,
          "firstPaymentReferenceId": null,
          "secondPaymentReferenceId": null,
          "properties": null,
          "auditLogs": []
        }
      ],
      "paymentAttempts": null,
      "auditLogs": []
    },
    {
      "targetInvoiceId": "e8dbe200-0738-4317-9c74-581696a0b4e9",
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "paymentId": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
      "paymentNumber": "42",
      "paymentExternalKey": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
      "authAmount": 0,
      "capturedAmount": 0,
      "purchasedAmount": 100,
      "refundedAmount": 0,
      "creditedAmount": 0,
      "currency": "USD",
      "paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
      "transactions": [
        {
          "transactionId": "60c4ffe7-f67c-456d-955d-6d35d2cd3fd2",
          "transactionExternalKey": "60c4ffe7-f67c-456d-955d-6d35d2cd3fd2",
          "paymentId": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
          "paymentExternalKey": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
          "transactionType": "PURCHASE",
          "amount": 100,
          "currency": "USD",
          "effectiveDate": "2023-08-28T16:27:44.000Z",
          "processedAmount": 100,
          "processedCurrency": "USD",
          "status": "SUCCESS",
          "gatewayErrorCode": null,
          "gatewayErrorMsg": null,
          "firstPaymentReferenceId": null,
          "secondPaymentReferenceId": null,
          "properties": null,
          "auditLogs": []
        }
      ],
      "paymentAttempts": null,
      "auditLogs": []
    },
    {
      "targetInvoiceId": "72662545-787c-4e9a-90af-4ac728392c35",
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "paymentId": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
      "paymentNumber": "43",
      "paymentExternalKey": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
      "authAmount": 0,
      "capturedAmount": 0,
      "purchasedAmount": 100,
      "refundedAmount": 0,
      "creditedAmount": 0,
      "currency": "USD",
      "paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
      "transactions": [
        {
          "transactionId": "aee6788b-526b-4c15-a943-b46bb9fe3ecf",
          "transactionExternalKey": "aee6788b-526b-4c15-a943-b46bb9fe3ecf",
          "paymentId": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
          "paymentExternalKey": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
          "transactionType": "PURCHASE",
          "amount": 100,
          "currency": "USD",
          "effectiveDate": "2023-08-28T16:27:44.000Z",
          "processedAmount": 100,
          "processedCurrency": "USD",
          "status": "SUCCESS",
          "gatewayErrorCode": null,
          "gatewayErrorMsg": null,
          "firstPaymentReferenceId": null,
          "secondPaymentReferenceId": null,
          "properties": null,
          "auditLogs": []
        }
      ],
      "paymentAttempts": null,
      "auditLogs": []
    },
    {
      "targetInvoiceId": "3a5d2748-88df-4f3f-bb60-49e8fbce1c0a",
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "paymentId": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
      "paymentNumber": "44",
      "paymentExternalKey": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
      "authAmount": 0,
      "capturedAmount": 0,
      "purchasedAmount": 500,
      "refundedAmount": 0,
      "creditedAmount": 0,
      "currency": "USD",
      "paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
      "transactions": [
        {
          "transactionId": "3f424634-7207-48fc-8de5-8bf2de229984",
          "transactionExternalKey": "3f424634-7207-48fc-8de5-8bf2de229984",
          "paymentId": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
          "paymentExternalKey": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
          "transactionType": "PURCHASE",
          "amount": 500,
          "currency": "USD",
          "effectiveDate": "2023-08-28T16:27:44.000Z",
          "processedAmount": 500,
          "processedCurrency": "USD",
          "status": "SUCCESS",
          "gatewayErrorCode": null,
          "gatewayErrorMsg": null,
          "firstPaymentReferenceId": null,
          "secondPaymentReferenceId": null,
          "properties": null,
          "auditLogs": []
        }
      ],
      "paymentAttempts": null,
      "auditLogs": []
    },
    {
      "targetInvoiceId": null,
      "accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
      "paymentId": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
      "paymentNumber": "45",
      "paymentExternalKey": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
      "authAmount": 50,
      "capturedAmount": 0,
      "purchasedAmount": 0,
      "refundedAmount": 0,
      "creditedAmount": 0,
      "currency": "USD",
      "paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
      "transactions": [
        {
          "transactionId": "8c890167-62cc-4a13-b724-93b8274da3d5",
          "transactionExternalKey": "8c890167-62cc-4a13-b724-93b8274da3d5",
          "paymentId": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
          "paymentExternalKey": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
          "transactionType": "AUTHORIZE",
          "amount": 50,
          "currency": "USD",
          "effectiveDate": "2023-08-28T16:34:34.000Z",
          "processedAmount": 50,
          "processedCurrency": "USD",
          "status": "SUCCESS",
          "gatewayErrorCode": null,
          "gatewayErrorMsg": null,
          "firstPaymentReferenceId": null,
          "secondPaymentReferenceId": null,
          "properties": null,
          "auditLogs": []
        }
      ],
      "paymentAttempts": null,
      "auditLogs": []
    }
  ]
}

Query Parameters

Name Type Required Default Description
audit string false "NONE" Level of audit information to return: "NONE", "MINIMAL", or "FULL"

Response

If successful, returns a status code of 200 and a complete account record including: the account object; bundles with subscriptions and timelines giving all events; invoices; and payments including payment attempts.