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

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}

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);

{
  "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

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);

{
  "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}

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}

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.

List and Search

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

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();

{
  "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. 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.

HTTP Request

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

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"

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);

{
  "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
searchKey	string	true	none	What you want to find
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

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

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);

[
  {
  "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}

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

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);

[
  {
    "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

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);

[
  {
    "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.

HTTP Request

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

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);

[
   {
      "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.

HTTP Request

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

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);

[
   {
      "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
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

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

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);

[
   {
      "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

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);

[
   {
      "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

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

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

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

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);

[
  {
    "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

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

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

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);

{
  "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:

Scenario 1
- T1: Service A, State S1, isBlockBilling=true, isBlockEntitlement=false
- T2: Service A, State S1, isBlockBilling=false, isBlockEntitlement=true
- T3: Service A, State S2, isBlockBilling=false, isBlockEntitlement=false
- T4: Service A, State S2, isBlockBilling=false, isBlockEntitlement=false
Scenario 2
- T1: Service A, State S1, isBlockBilling=true, isBlockEntitlement=false
- T2: Service B, State S1, isBlockBilling=false, isBlockEntitlement=true
- T3: Service A, State S2, isBlockBilling=false, isBlockEntitlement=false
- T4: Service B, State S2, isBlockBilling=false, isBlockEntitlement=false

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

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

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);

[
  {
    "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

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);

[
   {
      "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

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

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

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);

[
  {
    "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

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);

[
  {
    "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

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

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.

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"

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"

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.

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

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);

[
  {
    "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

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);

[
  {
    "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

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);

[
  {
    "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.

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);

[
  {
    "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

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);

{
  "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.

Account

Account Resource

Accounts

Create an Account

Retrieve an Account by its ID

Retrieve an Account by its external key

Update an Account

Close account

List and Search

List accounts

Search accounts

Email

Add account email

Retrieve account emails

Delete email

Bundle

Retrieve bundles for account

Retrieve paginated bundles for account

Invoice

Retrieve account invoices

Retrieve paginated account invoices

Payment

Trigger a payment for all unpaid invoices

Retrieve account invoice payments

Retrieve account payments

Trigger a payment (authorization, purchase or credit)

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

Payment Method

Add a payment method

Retrieve account payment methods

Set the default payment method

Refresh account payment methods

Overdue

Retrieve overdue state for account

Blocking State

Blocking State Resource

Block an account

Retrieve blocking states for account

Hierarchical Accounts

List child accounts

Transfer a given child credit to the parent level

Custom Fields

Add custom fields to account

Retrieve all custom fields

Retrieve account custom fields

Modify custom fields for an account

Remove custom fields from account

Tags

Add tags to account

Retrieve all tags

Retrieve account tags

Remove tags from account

Audit Logs

Retrieve audit logs

Retrieve account audit logs with history

Retrieve account email audit logs with history

Retrieve blocking state audit logs with history

Retrieve account timeline