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 |
| string | user | Primary email to reach the customer | |
| notes | string | user | Additonal notes about the customer, usually set by the customer service department |
| isMigrated | boolean | user | Indicates whether this account has been migrated from another system |
| accountCBA | integer | system | Account credit, if any |
| accountBalance | integer | system | Account balance, if any |
| auditLogs | array | system | Array of audit log records for this account |
The name is usually the personal name of the account owner. We recommend that this be entered so that the first word is an acceptable short form for the complete name, such as "first name" in most English-speaking cultures. In this case the value firstNameLength enables your code to extract this part of the name for informal greetings. For information on name formats in various countries see Personal Names around the World by the W3C.
A list of valid timeZone strings is given at timezone strings.
For information about migrating accounts from a previous system see the Migration Guide.
Accounts
Create an Account
Create a new customer Account.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "name": "John Doe", "email": "[email protected]", "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("[email protected]");
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 = "[email protected]"
account.currency = "USD"
account.create(user, reason, comment, options)
accountApi = killbill.AccountApi()
body = Account(name='John Doe',
email='[email protected]',
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: '[email protected]',currency: 'USD'};
api.createAccount(body,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$account = new Account();
$account->setName('TestPHPAccount');
$account->setEmail('[email protected]');
$account->setCurrency('USD');
$apiInstance->createAccount($account,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);
Request Body
The body of the request is a JSON string specifying any attributes of the resource that need to be assigned an initial value. No attributes are required. For any attributes omitted, the following defaults are generated:
| Attribute | Default |
|---|---|
| accountId | System generated UUID |
| externalKey | Copy of accountId |
| billCycleDayLocal | 0 |
| isPaymentDelegatedToParent | false |
| referenceTime | ISO time-date code for the current time in the specified timezone |
| timeZone | "UTC" |
| all others | null |
All attributes are optional, so it is possible to quickly create a shell account. This account could be used for test purposes, so its attributes can be filled in later. This also ensures the initial account contains no PII. Note, however, that the currency attribute must have a non-null value. This cannot be added later and is required for invoicing to work properly.
A few fields are not updatable; they can only be set once when creating the original Account. These include externalKey, currency, timeZone, and referenceTime. In addition the billCycleDayLocal can be updated but only once, that is one can create an Account without specifying the billCycleDayLocal and later update its value; this, in particular allows the system to update its value to a good default, that is one that will avoid leading prorations, when creating the first subscription.
The accountId and audit logs are generated by the system and cannot be set or modified by the user.
In order to create an account as a child account, the parentAccountId attribute needs to be specified with the id of the parent account. Also, the isPaymentDelegatedToParent attribute can be specified with a true/false value. A false indicates that the child account will be responsible for paying its own invoices while a true indicates that the parent account will be responsible for paying the child account invoices.
Query Parameters
none
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the account object, including the generated accountId.
Retrieve an Account by its ID
Retrieves the full resource object for an Account using its accountId.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/36c05a84-563b-4794-8958-772d93e677e1"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("36c05a84-563b-4794-8958-772d93e677e1");
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info
Account result = accountApi.getAccount(accountId,
accountWithBalance,
accountWithBalanceAndCBA,
AuditLevel.NONE,
requestOptions);
account_id = "36c05a84-563b-4794-8958-772d93e677e1"
with_balance = false
with_balance_and_cba = false
account = KillBillClient::Model::Account
accountResponse = account.find_by_id( account_id,
with_balance,
with_balance_and_cba,
options)
accountApi = killbill.AccountApi()
account_id = '36c05a84-563b-4794-8958-772d93e677e1'
account = accountApi.get_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '36c05a84-563b-4794-8958-772d93e677e1';
const response: AxiosResponse<killbill.Account> = await api.getAccount(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '36c05a84-563b-4794-8958-772d93e677e1';
$account = $apiInstance->getAccount($accountID);
Example Response:
{
"accountId": "36c05a84-563b-4794-8958-772d93e677e1",
"name": "John Doe",
"firstNameLength": null,
"externalKey": "36c05a84-563b-4794-8958-772d93e677e1",
"email": "[email protected]",
"billCycleDayLocal": 0,
"currency": "USD",
"parentAccountId": null,
"isPaymentDelegatedToParent": false,
"paymentMethodId": null,
"referenceTime": "2023-03-08T16:31:16.000Z",
"timeZone": "UTC",
"address1": null,
"address2": null,
"postalCode": null,
"company": null,
"city": null,
"state": null,
"country": null,
"locale": null,
"phone": null,
"notes": null,
"isMigrated": null,
"accountBalance": null,
"accountCBA": null,
"auditLogs": []
}
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| accountWithBalance | boolean | false | false | If true, returns accountBalance info |
| accountWithBalanceAndCBA | boolean | false | false | If true, returns accountBalance and accountCBA info |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and an account object in the response body.
Retrieve an Account by its external key
Retrieves the resource object for an Account using its externalKey as an identifier.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts?externalKey=36c05a84-563b-4794-8958-772d93e677e1"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
String externalKey = "36c05a84-563b-4794-8958-772d93e677e1";
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info
Account result = accountApi.getAccountByKey(externalKey,
accountWithBalance,
accountWithBalanceAndCBA,
AuditLevel.NONE,
requestOptions);
external_key = '36c05a84-563b-4794-8958-772d93e677e1'
with_balance = false
with_balance_and_cba = false
account = KillBillClient::Model::Account
accountResponse = account.find_by_external_key( external_key,
with_balance,
with_balance_and_cba,
options)
accountApi = killbill.AccountApi()
external_key = '36c05a84-563b-4794-8958-772d93e677e1'
account = accountApi.get_account_by_key(external_key)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const externalKey = 'external_key';
const response: AxiosResponse<killbill.Account, any> = await api.getAccountByKey(externalKey);
$apiInstance = $client->getAccountApi();
$externalKey = 'external_key';
$account = $apiInstance->getAccountByKey($externalKey);
Example Response:
{
"accountId": "36c05a84-563b-4794-8958-772d93e677e1",
"name": "John Doe",
"firstNameLength": null,
"externalKey": "36c05a84-563b-4794-8958-772d93e677e1",
"email": "[email protected]",
"billCycleDayLocal": 0,
"currency": "USD",
"parentAccountId": null,
"isPaymentDelegatedToParent": false,
"paymentMethodId": null,
"referenceTime": "2023-03-08T16:31:16.000Z",
"timeZone": "UTC",
"address1": null,
"address2": null,
"postalCode": null,
"company": null,
"city": null,
"state": null,
"country": null,
"locale": null,
"phone": null,
"notes": null,
"isMigrated": null,
"accountBalance": null,
"accountCBA": null,
"auditLogs": []
}
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| externalKey | string | true | none | External key to be used for retrieval |
| accountWithBalance | boolean | false | false | If true, returns accountBalance info |
| accountWithBalanceAndCBA | boolean | false | false | If true, returns accountBalance and accountCBA info |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and an account object in the response body.
Update an Account
Updates selected attributes in an account object. Note that the following fields are not updatable; they can only be set once when creating the original Account: externalKey, currency, timeZone, and referenceTime. In addition, the billCycleDayLocal can be updated but only once, that is, one can create an Account without specifying the billCycleDayLocal and later update its value. This, allows the system to update its value to a good default, that is one that will avoid leading prorations, when creating the first subscription. Also, the audit logs cannot be changed.
The updates are passed in the request body, as an object that only needs to contain the attributes to be changed. Any attribute omitted from the request body will remain unchanged.
If the boolean query parameter treatNullAsReset is true, any attribute specified as null in the request will be set to null. If the parameter is false, any attribute specified as null in the request will remain unchanged.
HTTP Request
PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}
Example Request:
curl -v \
-X PUT \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "name": "Another Name"}' \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
Account body = new Account();
body.setAccountId(accountId);
body.setName("Another Name");
Boolean treatNullAsReset = false; // any attribute with a null value in the request body will be unchanged
// If set to true, you will need to explicitly set the externalKey, currency and timezone fields to their original values, otherwise a KillBillClientException will occur.
accountApi.updateAccount(accountId,
body,
treatNullAsReset,
requestOptions);
account = KillBillClient::Model::Account.new
user = 'user'
reason = 'reason'
comment = 'comment'
account.account_id = "07c0cef4-41c5-4606-b2cd-661332cdd41c"
account.name = 'Another Name'
treat_null_as_reset = false
account.update(treat_null_as_reset,user,reason,comment,options)
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
body = Account(name='Another Name')
accountApi.update_account(account_id,
body,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.Account = {name: 'Another Name'};
api.updateAccount(body,'07c0cef4-41c5-4606-b2cd-661332cdd41c','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$account = new Account();
$account->setName('Another Name');
$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
$apiInstance->updateAccount($account,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| treatNullAsReset | boolean | false | false | If true, any attribute with a null value in the request body will be set to null. If false, any attribute with a null value in the request body will be unchanged. |
Response
If successful, returns a status code of 204 and an empty body..
Close account
This endpoint can be used when no other state change will occur on this Account to bring it to a stable state. Depending on the value of the query parameters it will potentially cancel all active subscriptions, write-off unpaid invoices, etc. This endpoint is not for account deletion. We provide no support to remove state through APIs; such deletion operations, if really needed, would have to happen at the database level and are not encouraged. They can be tricky to get right.
HTTP Request
DELETE http://127.0.0.1:8080/1.0/kb/accounts/{accountId}
Example Request:
curl -v \
-X DELETE \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/8785164f-b5d7-4da1-9495-33f5105e8d80"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
Boolean cancelAllSubscriptions = true; // Will cancel all subscriptions
Boolean writeOffUnpaidInvoices = true; // Will write off unpaid invoices
Boolean itemAdjustUnpaidInvoices = false; // Will not adjust unpaid invoices
Boolean removeFutureNotifications = true; // Will remove future notifications
accountApi.closeAccount(accountId,
cancelAllSubscriptions,
writeOffUnpaidInvoices,
itemAdjustUnpaidInvoices,
removeFutureNotifications,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = "864c1418-e768-4cd5-a0db-67537144b685"
user = 'user'
reason = 'reason'
comment = 'comment'
cancel_subscriptions = false
writeoff_unpaid_invoices = false
item_adjust_unpaid_invoices = false
account.close(cancel_subscriptions,
writeoff_unpaid_invoices,
item_adjust_unpaid_invoices,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
accountApi.close_account( account_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
api.closeAccount(accountID,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
$apiInstance->closeAccount($accountID,$xKillbillCreatedBy);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| cancelAllSubscriptions | boolean | false | false | If true, cancel all subscriptions |
| writeOffUnpaidInvoices | boolean | false | false | If true, write off unpaid invoices |
| itemAdjustUnpaidInvoices | boolean | false | false | If true, adjust unpaid invoices |
| removeFutureNotifications | boolean | false | false | If true, remove future notifications |
Response
IF successful, returns a status code of 204 and an empty body.
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
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/pagination"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
Long offset = 0L;
Long limit = 1L;
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info
Accounts allAccounts = accountApi.getAccounts(offset,
limit,
accountWithBalance,
accountWithBalanceAndCBA,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account
offset = 0
limit = 100
with_balance = false
with_balance_and_cba = false
allAccounts = account.find_in_batches( offset,
limit,
with_balance,
with_balance_and_cba,
options)
accountApi = killbill.AccountApi()
allAccounts = accountApi.get_accounts()
const api: killbill.AccountApi = new killbill.AccountApi(config);
const response: AxiosResponse<killbill.Account[], any> = await api.getAccounts();
$apiInstance = $client->getAccountApi();
$accounts = $apiInstance->getAccounts();
Example Response:
{
"next": [
{
"auditLogs": [],
"externalKey": "e60a79de-0d4c-4aeb-82e9-7695fe393b81",
"accountId": "e60a79de-0d4c-4aeb-82e9-7695fe393b81",
"referenceTime": {
"year": 2023,
"dayOfYear": 65,
"equalNow": false,
"weekyear": 2023,
"chronology": {
"zone": {
"ID": "UTC"
}
},
"weekOfWeekyear": 10,
"secondOfMinute": 39,
"millisOfDay": 61959000,
"monthOfYear": 3,
"dayOfWeek": 1,
"beforeNow": true,
"minuteOfDay": 1032,
"dayOfMonth": 6,
"era": 1,
"zone": {
"ID": "UTC"
},
"yearOfCentury": 23,
"centuryOfEra": 20,
"hourOfDay": 17,
"secondOfDay": 61959,
"millis": 1678122759000,
"yearOfEra": 2023,
"minuteOfHour": 12,
"millisOfSecond": 0,
"afterNow": false
},
"paymentDelegatedToParent": false,
"name": "John Doe",
"timeZone": "UTC",
"currency": "USD",
"billCycleDayLocal": 0,
"email": "[email protected]"
}
],
"paginationNextOffset": 1,
"paginationNextPageUri": "/1.0/kb/accounts/pagination?offset=1&limit=1&accountWithBalanceAndCBA=false&accountWithBalance=false&audit=NONE",
"paginationMaxNbRecords": 5,
"killBillHttpClient": {},
"paginationCurrentOffset": 0,
"paginationTotalNbRecords": 5,
"empty": false
}
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| offset | long | false | 0 | Starting index for items listed |
| limit | long | false | 100 | Maximum number of items to be listed |
| accountWithBalance | boolean | false | false | If true, returns accountBalance info |
| accountWithBalanceAndCBA | boolean | false | false | If true, returns accountBalance and accountCBA info |
Response
If successful, returns a status code of 200 and a list of all accounts.
Search accounts
Search for an account by a specified search string. Search operation can be of two types as follows:
Basic:
The search string is compared to the following attributes: accountId, name, email, companyName, and externalKey. The operation returns the account record in which the search string matches all or part of any one of the attributes name, email, companyName, externalKey. However, the string must match the entire attribute in case of accountId.
For example : An account with name exampleaccount can be searched using example as the search string. However, an account with accountId 9254283b-be25-45f1-97c3-b902f4d18bab cannot be searched using only 9254283b as the search string.
Advanced:
Advanced search allows filtering on the specified fields. The prefix marker _q=1 needs to be specified at the beginning of the search key to indicate this is an advanced query.
The search key should be in the following format: <field>[<operator>]=value. Here:
field: The name of the field you want to filter by. Possible values are:- id
- external_key
- name
- first_name_length
- currency
- billing_cycle_day_local,
- parent_account_id
- is_payment_delegated_to_parent,
- payment_method_id
- reference_time
- time_zone
- locale
- address1
- address2
- company_name
- city
- state_or_province
- country
- postal_code
- phone
- notes
- migrated
- created_by
- created_date
- updated_by
- updated_date
<operator>: The comparison operator. This is optional and defaults to the equal to (=) operator if not specified. Possible values are:- and
- eq
- gte
- gt
- like
- lte
- lt
- neq
- or
value: The value to be used for filtering.
Some advanced search key examples:
- _q=1&[email protected]¤cy=USD - Return accounts where
emailis[email protected]andcurrencyisUSD - _q=1&address2[like]=Poit% - Returns accounts where
address2starts withPoit - _q=1&address2=Poitier¤cy[neq]=MXN - Returns accounts where
currencyis notMXN - _q=1&billing_cycle_day_local[gte]=31¤cy=USD - Returns accounts where
BCDis greater than31andcurrencyisUSD.
Note: The symbols [,],% need to be URL encoded while using cURL/Postman as follows:
| Symbol | Encoding |
|---|---|
| [ | %5B |
| ] | %5D |
| % | %25 |
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/search/{searchKey}
Example Request:
## Basic Search
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/search/John%20Doe"
## Advanced Search (search by email and currency)
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/search/_q=1&[email protected]¤cy=USD"
## Advanced Search (search with operator)
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/search/_q=1&email%5Blike%5D=john%25"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
String searchKey = "John";
Long offset = 0L;
Long limit = 1L;
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info
List<Account> accountsByKey = accountApi.searchAccounts(searchKey,
offset,
limit,
accountWithBalance,
accountWithBalanceAndCBA,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account
search_key = 'John'
offset = 0
limit = 100
with_balance = false
with_balance_and_cba = false
accounts = account.find_in_batches_by_search_key( search_key,
offset,
limit,
with_balance,
with_balance_and_cba,
options)
accountApi = killbill.AccountApi()
search_key = 'John'
accounts = accountApi.search_accounts(search_key)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const searchKey = 'search_key';
const response: AxiosResponse<killbill.Account[], any> = await api.searchAccounts(searchKey);
$apiInstance = $client->getAccountApi();
$searchKey = 'search_key';
$accounts = $apiInstance->searchAccounts($searchKey);
Example Response:
{
"next": [
{
"auditLogs": [],
"accountId": "fc693517-9ede-4543-a184-9e6f21119584",
"externalKey": "fc693517-9ede-4543-a184-9e6f21119584",
"referenceTime": {
"year": 2023,
"dayOfYear": 65,
"equalNow": false,
"weekyear": 2023,
"chronology": {
"zone": {
"ID": "UTC"
}
},
"weekOfWeekyear": 10,
"secondOfMinute": 21,
"millisOfDay": 62241000,
"monthOfYear": 3,
"dayOfWeek": 1,
"beforeNow": true,
"minuteOfDay": 1037,
"dayOfMonth": 6,
"era": 1,
"zone": {
"ID": "UTC"
},
"yearOfCentury": 23,
"hourOfDay": 17,
"centuryOfEra": 20,
"secondOfDay": 62241,
"millis": 1678123041000,
"yearOfEra": 2023,
"minuteOfHour": 17,
"millisOfSecond": 0,
"afterNow": false
},
"paymentDelegatedToParent": false,
"name": "John Doe",
"timeZone": "UTC",
"currency": "USD",
"billCycleDayLocal": 0,
"email": "[email protected]"
}
],
"paginationNextOffset": 1,
"paginationNextPageUri": "/1.0/kb/accounts/search/John?offset=1&limit=1&accountWithBalanceAndCBA=false&accountWithBalance=false&audit=NONE",
"paginationMaxNbRecords": 5,
"killBillHttpClient": {},
"paginationCurrentOffset": 0,
"paginationTotalNbRecords": 4,
"empty": false
}
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| offset | long | false | 0 | Starting index for items listed |
| limit | long | false | 100 | Maximum number of items to return on this page |
| accountWithBalance | boolean | false | false | If true, returns accountBalance info |
| accountWithBalanceAndCBA | boolean | false | false | If true, returns accountBalance and accountCBA info |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a list of accounts that contain a match for the specified search key.
These endpoints manage emails associated with a customer account. These are secondary emails, distinct from the email attribute in the account object. It is possible to have
several such emails for one customer account.
Add account email
Add an email to an account. Existing emails are undisturbed.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "email": "[email protected]"}' \
"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 protected]";
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 protected]'
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 protected]')
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 protected]' };
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 protected]');
$accountEmail->setAccountId('03fc2b57-06be-4691-a260-c897d5c1e13e');
$accountID = '03fc2b57-06be-4691-a260-c897d5c1e13e';
$apiInstance->addEmail($accountEmail,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);
Request Body
The request body identifies a subset of the account attributes as a JSON string. The attributes required are accountId and email (the email to be added). accountId is required in the body even though it is given in the path. No other attributes should be included.
Query Parameters
None.
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the account object, including the accountId.
Retrieve account emails
Retrieves all emails for an account
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("cd026587-c93b-471c-a98d-224c21636fbc");
List<AccountEmail> emails = accountApi.getEmails(accountId, requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'cd026587-c93b-471c-a98d-224c21636fbc'
audit = 'NONE'
accountEmails = account.emails(audit, options)
accountApi = killbill.AccountApi()
account_id = 'c8f51346-562d-429b-8c89-27a0f72009b3'
accountEmails = accountApi.get_emails(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'f7fde238-850a-4a7b-b075-48b582ee3495';
const response: AxiosResponse<killbill.AccountEmail[], any> = await api.getEmails(accountID);
$apiInstance = $client->getAccountApi();
$accountID = 'f7fde238-850a-4a7b-b075-48b582ee3495';
$emails = $apiInstance->getEmails($accountID);
Example Response:
[
{
"accountId":"e4ca38b3-934d-42e8-a292-ffb0af5549f2",
"email":"[email protected]"
}
]
Query Parameters
None.
Response Body
If successful, returns a status code of 200 and a list of objects giving the account id and the emails. Note that this is not the full object for each email, and does not include the email ID. This can be obtained only from the account audit log.
Delete email
Deletes an email from an account
HTTP Request
DELETE http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails/{email}
Example Request:
curl -v \
-X DELETE \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails/[email protected]"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("873c26ef-a3fa-4942-b2f5-549b51f20b1a");
String email = "[email protected]";
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 protected]'
account.remove_email(email,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = 'c84de569-b654-4f7f-ab13-17616302d310'
email = '[email protected]'
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 protected]';
api.removeEmail(accountID,email,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$accountID = 'be484bff-58dc-4ceb-906f-61dc9e317b0f';
$accountEmail = '[email protected]';
$apiInstance->removeEmail($accountID,$accountEmail,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);
Query Parameters
None.
Response
If successful, returns a status code of 204 and without any data.
Bundle
This endpoint provides an API to list the Bundles associated with this account. A Bundle is a set of Subscriptions and related information. See Bundle for details on Bundles.
Retrieve bundles for account
This endpoint is used to list all Bundles associated with this account. It is possible to limit the list to a specific Bundle external key, or to a list of Bundle Ids.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/bundles
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/bundles"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("15434b45-54c1-4a44-851c-b1f2f7a52f03");
String externalKey = "123467"; //use null to fetch all bundles
String bundlesFilter = null;
List<Bundle> accountBundles = accountApi.getAccountBundles(accountId,
externalKey,
bundlesFilter,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '15434b45-54c1-4a44-851c-b1f2f7a52f03'
accountBundles = account.bundles(options)
accountApi = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
accountBundles = accountApi.get_account_bundles(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
const response: AxiosResponse<killbill.Bundle[], any> = await api.getAccountBundles(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
$bundles = $apiInstance-> getAccountBundles($accountID);
Example Response:
[
{
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"subscriptions": [
{
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"startDate": "2018-07-18",
"productName": "Standard",
"productCategory": "BASE",
"billingPeriod": "MONTHLY",
"phaseType": "TRIAL",
"priceList": "DEFAULT",
"planName": "standard-monthly",
"state": "ACTIVE",
"sourceType": "NATIVE",
"cancelledDate": null,
"chargedThroughDate": null,
"billingStartDate": "2018-07-18",
"billingEndDate": null,
"billCycleDayLocal": 17,
"events": [
{
"eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-08-17",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "PHASE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement+billing-service",
"serviceStateName": "PHASE",
"phase": "standard-monthly-evergreen",
"auditLogs": []
}
],
"priceOverrides": null,
"prices": [
{
"planName": "standard-monthly",
"phaseName": "standard-monthly-trial",
"phaseType": "TRIAL",
"fixedPrice": 0,
"recurringPrice": null,
"usagePrices": []
},
{
"planName": "standard-monthly",
"phaseName": "standard-monthly-evergreen",
"phaseType": "EVERGREEN",
"fixedPrice": null,
"recurringPrice": 100,
"usagePrices": []
}
],
"auditLogs": []
}
],
"timeline": {
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"events": [
{
"eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-08-17",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "PHASE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement+billing-service",
"serviceStateName": "PHASE",
"phase": "standard-monthly-evergreen",
"auditLogs": []
}
],
"auditLogs": []
},
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| externalKey | string | false | return all bundles | Bundle external key; if present, return only bundles with this key. |
| bundlesFilter | string | false | return all bundles | Comma separated list of bundle ids to return, if found. |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Returns
If successful, returns a status code of 200 and a list of bundle objects.
Retrieve paginated bundles for account
This endpoint is used to list all Bundles associated with this account in a paginated format.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/bundles/pagination
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/325fbe1c-7c35-4d96-a4e5-2cbaabe218c6/bundles/pagination"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("325fbe1c-7c35-4d96-a4e5-2cbaabe218c6");
Long offset = 0L;
Long limit = 10L;
Bundles bundles = accountApi.getAccountBundlesPaginated(accountId, offset, limit, AuditLevel.NONE, requestOptions);
account_id = '325fbe1c-7c35-4d96-a4e5-2cbaabe218c6'
offset = 0
limit = 100
audit = 'NONE'
bundles = KillBillClient::Model::Account.paginated_bundles(account_id, offset, limit, audit, options)
accountApi = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
accountBundles = accountApi.get_account_bundles_paginated(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
const response: AxiosResponse<killbill.Bundle[], any> = await api.getAccountBundlesPaginated(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
$bundles = $apiInstance-> getAccountBundlesPaginated($accountID);
Example Response:
[
{
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"subscriptions": [
{
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"startDate": "2018-07-18",
"productName": "Standard",
"productCategory": "BASE",
"billingPeriod": "MONTHLY",
"phaseType": "TRIAL",
"priceList": "DEFAULT",
"planName": "standard-monthly",
"state": "ACTIVE",
"sourceType": "NATIVE",
"cancelledDate": null,
"chargedThroughDate": null,
"billingStartDate": "2018-07-18",
"billingEndDate": null,
"billCycleDayLocal": 17,
"events": [
{
"eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-08-17",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "PHASE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement+billing-service",
"serviceStateName": "PHASE",
"phase": "standard-monthly-evergreen",
"auditLogs": []
}
],
"priceOverrides": null,
"prices": [
{
"planName": "standard-monthly",
"phaseName": "standard-monthly-trial",
"phaseType": "TRIAL",
"fixedPrice": 0,
"recurringPrice": null,
"usagePrices": []
},
{
"planName": "standard-monthly",
"phaseName": "standard-monthly-evergreen",
"phaseType": "EVERGREEN",
"fixedPrice": null,
"recurringPrice": 100,
"usagePrices": []
}
],
"auditLogs": []
}
],
"timeline": {
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
"events": [
{
"eventId": "3961e5a4-815c-4e95-aca6-2f3e76c37942",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "8e7a6a7d-7660-49e3-979c-a4a0b6ec6804",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-07-18",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "standard-monthly-trial",
"auditLogs": []
},
{
"eventId": "f058c95f-9a86-435b-8bba-4f8532635450",
"billingPeriod": "MONTHLY",
"effectiveDate": "2018-08-17",
"plan": "standard-monthly",
"product": "Standard",
"priceList": "DEFAULT",
"eventType": "PHASE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement+billing-service",
"serviceStateName": "PHASE",
"phase": "standard-monthly-evergreen",
"auditLogs": []
}
],
"auditLogs": []
},
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| offset | long | false | 0 | Starting index for items listed |
| limit | long | false | 100 | Maximum number of items to be listed |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Returns
If successful, returns a status code of 200 and a list of bundle objects.
Invoice
This endpoint provides an API to list the Invoices associated with this account. See section Invoice for details on invoices.
Retrieve account invoices
List the Invoices associated with this account. Note that this endpoint returns shallow invoices (the value 0 is returned for the amount, creditAdj, refundAdj and balance fields) unless includeInvoiceComponents=true is specified.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoices"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("d3a82897-ae72-4a2e-9bca-e3c1fe087f84");
LocalDate startDate = null;
LocalDate endDate = null;
Boolean withMigrationInvoices = false; // Will not fetch migrated invoice - if any
Boolean unpaidInvoicesOnly = false; // Will not restrict to unpaid invoices
Boolean includeVoidedInvoices = false; // Will not include void invoices
Boolean includeInvoiceComponents = false; //Will not include invoice components like invoice items/payments, etc.
String invoicesFilter = null;
Invoices invoices = accountApi.getInvoicesForAccount(accountId,
startDate,
endDate,
withMigrationInvoices,
unpaidInvoicesOnly,
includeVoidedInvoices,
includeInvoiceComponents,
invoicesFilter,
AuditLevel.FULL,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
accountInvoices = account.invoices(options)
accountApi = killbill.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
accountInvoices = accountApi.get_invoices_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
const response: AxiosResponse<killbill.Invoice[], any> = await api.getInvoicesForAccount(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
$invoices = $apiInstance-> getInvoicesForAccount($accountID);
Example Response:
[
{
"amount":50.0,
"currency":"USD",
"status":"COMMITTED",
"creditAdj":0.0,
"refundAdj":0.0,
"invoiceId":"d981abbb-3622-487a-9564-d594c9d04f83",
"invoiceDate":"2013-08-01",
"targetDate":"2013-08-01",
"invoiceNumber":"1563",
"balance":0.0,
"accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
"items":[
{
"invoiceItemId":"5f3b4e9c-66bd-4c5c-b84a-4ae951cc2f1d",
"invoiceId":"d981abbb-3622-487a-9564-d594c9d04f83",
"accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
"itemType":"EXTERNAL_CHARGE",
"description":"Some description",
"startDate":"2013-08-01",
"amount":50.0,
"currency":"USD",
"auditLogs":[]
}
],
"isParentInvoice":false,
"auditLogs":[]
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| startDate | date | false | no starting date | Return only invoices issued since this date. |
| endDate | date | false | no ending date | Return only invoices issued up to this date. |
| withMigrationInvoices | boolean | false | false | Choose true to include migration invoices |
| unpaidInvoicesOnly | boolean | false | false | Choose true to include unpaid invoices only |
| includeVoidedInvoices | boolean | false | false | Choose true to include voided invoices |
| includeInvoiceComponents | boolean | false | false | Choose true to include invoice components (like invoice items/payments, etc.) |
| invoicesFilter | string | false | empty | A comma separated list of invoiceIds to filter |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
For information about migration and migration invoices, see the Migration Guide.
Response
If successful, returns a status of 200 and a list of invoice objects for this account.
Retrieve paginated account invoices
List the Invoices associated with this account in a paginated format. Note that this endpoint return shallow objects (the value 0 is returned for the amount, creditAdj, refundAdj and balance fields). In order to retrieve the account invoices with the actual data for these fields, you could use the non-paginated retrieve account invoices endpoint with includeInvoiceComponents=true. Alternatively, you could also use the retrieve invoice by id to obtain the complete invoice data for an individual invoice.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoices/pagination
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/325fbe1c-7c35-4d96-a4e5-2cbaabe218c6/invoices/pagination"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("325fbe1c-7c35-4d96-a4e5-2cbaabe218c6");
Long offset = 0L;
Long limit = 10L;
Invoices invoices = accountApi.getInvoicesForAccountPaginated(accountId, offset, limit, AuditLevel.NONE, requestOptions);
account_id = '325fbe1c-7c35-4d96-a4e5-2cbaabe218c6'
offset = 0
limit = 100
audit = 'NONE'
invoices = KillBillClient::Model::Account.paginated_invoices(account_id, offset, limit, audit, options)
accountApi = killbill.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
accountInvoices = accountApi.get_invoices_for_account_paginated(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
const response: AxiosResponse<killbill.Invoice[], any> = await api.getInvoicesForAccountPaginated(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
$invoices = $apiInstance-> getInvoicesForAccountPaginated($accountID);
Example Response:
[
{
"amount": 0,
"currency": "USD",
"status": "COMMITTED",
"creditAdj": 0,
"refundAdj": 0,
"invoiceId": "92d62ac0-606a-4f31-bb83-e03883cff710",
"invoiceDate": "2024-09-19",
"targetDate": "2024-09-19",
"invoiceNumber": "46166",
"balance": 0,
"accountId": "73c90e84-42dc-406a-be87-b75c45e581a2",
"bundleKeys": null,
"credits": null,
"items": [],
"trackingIds": [],
"isParentInvoice": false,
"parentInvoiceId": null,
"parentAccountId": null,
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| offset | long | false | 0 | Starting index for items listed |
| limit | long | false | 100 | Maximum number of items to be listed |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
For information about migration and migration invoices, see the Migration Guide.
Response
If successful, returns a status of 200 and a list of invoice objects for this account.
Payment
These endpoints are used to make or manage payments associated with this account. See section Payment for details on payments.
Trigger a payment for all unpaid invoices
Initiate payments for any unpaid invoices. This API allows you to make a series of payment calls, one against each unpaid invoice, using a specific payment method.
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for fetching the paid invoices. If no payments were made, returns a 204 status code.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoicePayments
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoicePayments?paymentMethodId=f835c556-0694-4883-b4c1-d1b6e308409b"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e011caa5-ba35-4ac6-81cb-63b4f08122dc");
UUID paymentMethodId = null;
Boolean externalPayment = true; // Will use a external payment method
BigDecimal paymentAmount = null;
LocalDate targetDate = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
accountApi.payAllInvoices(accountId,
paymentMethodId,
externalPayment,
paymentAmount,
targetDate,
NULL_PLUGIN_PROPERTIES,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
invoice_payment = KillBillClient::Model::InvoicePayment.new
invoice_payment.account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
external_payment = true
payment_method_id = nil
target_date = nil
invoice_payment.bulk_create(external_payment,
payment_method_id,
target_date,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
accountApi.pay_all_invoices(account_id,
external_payment=True,
payment_method_id=None,
target_date=None,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
api.payAllInvoices(accountID,'created_by');
$apiInstance = $client->getAccountApi();
$accountID = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266';
$xKillbillCreatedBy = "user";
$apiInstance-> payAllInvoices($accountID,$xKillbillCreatedBy);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| paymentMethodId | string | false | default payment method | Payment method id |
| externalPayment | boolean | false | false | Choose true if you use a external payment method. |
| paymentAmount | string | false | total balance | Total payment amount |
| targetDate | string | false | current date | Date for which payment should be made |
Response
If successful, returns a status code of 204 without any data.
Retrieve account invoice payments
Retrieve a list of payments made against invoices for this account.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/invoicePayments
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/invoicePayments"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e011caa5-ba35-4ac6-81cb-63b4f08122dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
InvoicePayments result = accountApi.getInvoicePayments(accountId,
NULL_PLUGIN_PROPERTIES,
requestOptions);
audit ='NONE'
with_plugin_info = false
with_attempts = false
account = KillBillClient::Model::Account.new
account.account_id = 'e011caa5-ba35-4ac6-81cb-63b4f08122dc'
accountInvoicePayments = account.invoice_payments( audit,
with_plugin_info,
with_attempts,
options)
accountApi = killbill.AccountApi()
account_id = '110952d7-1b7e-482c-b6bb-103e46794927'
accountInvoicePayments = accountApi.get_invoice_payments(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '110952d7-1b7e-482c-b6bb-103e46794927';
const response: AxiosResponse<killbill.InvoicePayment[], any> = await api.getInvoicePayments(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '110952d7-1b7e-482c-b6bb-103e46794927';
$invoicePayments = $apiInstance-> getInvoicePayments($accountID);
Example Response:
[
{
"targetInvoiceId":"d1d6e8d8-c476-4b53-badf-c23f78c02c09",
"accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
"paymentId":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
"paymentNumber":"319",
"paymentExternalKey":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
"authAmount":0,
"capturedAmount":0,
"purchasedAmount":50.0,
"refundedAmount":0,
"creditedAmount":0,
"currency":"USD",
"paymentMethodId":"6c064894-60cb-4d7e-a679-7b2464522968",
"transactions":[
{
"transactionId":"91c7363c-76b9-48f5-aafa-f098d4470a2a",
"transactionExternalKey":"91c7363c-76b9-48f5-aafa-f098d4470a2a",
"paymentId":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
"paymentExternalKey":"3f84661c-4fb7-42ac-8a02-3e8f48840e51",
"transactionType":"PURCHASE",
"amount":50.0,
"currency":"USD",
"effectiveDate":"2013-08-01T06:00:01.000Z",
"processedAmount":50.0,
"processedCurrency":"USD",
"status":"SUCCESS",
"auditLogs":[]
}
],
"auditLogs":[]
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| withPluginInfo | boolean | false | false | Choose true to include plugin info |
| withAttempts | boolean | false | false | Choose true to include payment attempts |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Returns
If successful, returns a status code of 200 and a list of invoice payment objects.
Retrieve account payments
Retrieve a list of payments made for this account. Payments are listed independent of any invoice.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/payments
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/payments"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e0fe95af-7d59-4b70-8252-165e1840410c");
Boolean withAttempts = false; // Will not reflect payment attempts
Boolean withPluginInfo = false; // Will not reflect payment attempts
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
Payments payments = accountApi.getPaymentsForAccount(accountId,
withAttempts,
withPluginInfo,
NULL_PLUGIN_PROPERTIES,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
accoountPayments = account.payments(options)
accountApi = killbill.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
accountPayments = accountApi.get_payments_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
const response: AxiosResponse<killbill.InvoicePayment[], any> = await api.getPaymentsForAccount(accountID);
$apiInstance = $client->getAccountApi();
$accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
$accountPayments = $apiInstance-> getPaymentsForAccount($accountID);
Example Response:
[
{
"accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
"paymentId":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
"paymentNumber":"325",
"paymentExternalKey":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
"authAmount":0,
"capturedAmount":0,
"purchasedAmount":50.0,
"refundedAmount":0,
"creditedAmount":0,
"currency":"USD",
"paymentMethodId":"6041ffab-ae5f-45d3-bdf8-ce8cbfa5fd5c",
"transactions":[
{
"transactionId":"be9dceca-9c5d-4038-818c-57e6fccfbe92",
"transactionExternalKey":"be9dceca-9c5d-4038-818c-57e6fccfbe92",
"paymentId":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
"paymentExternalKey":"b83132eb-1bf9-4a02-8572-376e4b1f06c9",
"transactionType":"PURCHASE",
"amount":50.0,
"currency":"USD",
"effectiveDate":"2013-08-01T06:00:02.000Z",
"processedAmount":50.0,
"processedCurrency":"USD",
"status":"SUCCESS",
"auditLogs":[
]
}
],
"auditLogs":[]
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| withPluginInfo | boolean | false | false | Choose true to include plugin info |
| withAttempts | boolean | false | false | Choose true to include payment attempts |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a list of payment objects.
Trigger a payment (authorization, purchase or credit)
This endpoint is part of the raw payment APIs, unreleated to subscriptions and invoices. It simply triggers a payment transaction against a particular payment gateway through the Kill Bill core and through the plugin communicating with the payment gateway. The transaction could be an authorization, a purchase, or a credit.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/payments
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "transactionType": "AUTHORIZE", "amount": 0}' \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/payments?paymentMethodId=c02fa9b0-ae95-42ae-9010-bc11cb160947"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("f4087a76-9f8a-4893-abbf-c5bb69975d1b");
PaymentTransaction authTransaction = new PaymentTransaction();
authTransaction.setAmount(BigDecimal.ONE);
authTransaction.setCurrency(account.getCurrency());
// TransactionType could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
authTransaction.setTransactionType(TransactionType.AUTHORIZE);
UUID paymentMethodId = UUID.fromString("1d55ed5f-deea-4109-98b0-beb13a242f7c");
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = accountApi.processPayment(accountId,
authTransaction,
paymentMethodId,
NULL_PLUGIN_NAMES,
NULL_PLUGIN_PROPERTIES,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
transaction = KillBillClient::Model::Transaction.new
transaction.amount = '50.0'
account_id = "f4087a76-9f8a-4893-abbf-c5bb69975d1b"
payment_method_id = "1d55ed5f-deea-4109-98b0-beb13a242f7c"
refresh_options = nil
# Authorization
transaction.auth(account_id,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
# Purchase
transaction.purchase(account_id,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
# Credit
transaction.credit(account_id,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
accountApi = killbill.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
payment_method_id = '80c7b386-97b2-424c-bb4e-0017f92bc6eb'
# transaction_type could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
body = PaymentTransaction(amount=50, transaction_type='AUTHORIZE')
accountApi.process_payment(account_id,
body,
payment_method_id=payment_method_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.PaymentTransaction = {amount: 50, transactionType: 'AUTHORIZE'};
api.processPayment(body,'b0da8392-49ba-43f2-8fac-3f9f85b8ff61','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$paymentTransaction = new PaymentTransaction();
$paymentTransaction->setAmount('50');
$paymentTransaction->setTransactionType('AUTHORIZE');
$accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
$apiInstance-> processPayment($paymentTransaction,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);
Request Body
The request body is a JSON string representing the payment transaction. See section Payment Transaction for details on payment transactions.
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| paymentMethodId | string | false | default payment method | payment method ID to use, if not default method |
| controlPluginName | array of strings | false | omit | list of control plugins, if any |
| pluginProperty | array of strings | false | omit | list of plugin properties, if any |
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment object, including the generated paymentId.
Trigger a payment (authorization, purchase or credit) using the account external key
This endpoint performs the same actions as the previous one, but the account is identified by its external key.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/payments
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "transactionType": "AUTHORIZE", "amount": 0}' \
"http://127.0.0.1:8080/1.0/kb/accounts/payments?externalKey=2ad52f53-85ae-408a-9879-32a7e59dd03d&paymentMethodId=c02fa9b0-ae95-42ae-9010-bc11cb160947"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
String externalKey = "ad70ffb1-3355-418a-a457-6d8d80696d02";
PaymentTransaction authTransaction = new PaymentTransaction();
authTransaction.setAmount(BigDecimal.ONE);
authTransaction.setCurrency(Currency.USD);//use currency associated with Account
// TransactionType could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
authTransaction.setTransactionType(TransactionType.AUTHORIZE);
UUID paymentMethodId = UUID.fromString("c6bd413e-268e-4cc8-afb0-16b2dec3ffa5");
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = accountApi.processPaymentByExternalKey(authTransaction,
externalKey,
paymentMethodId,
NULL_PLUGIN_NAMES,
NULL_PLUGIN_PROPERTIES,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
transaction = KillBillClient::Model::Transaction.new
transaction.amount = '50.0'
externalKey = "ad70ffb1-3355-418a-a457-6d8d80696d02";
payment_method_id = 'c6bd413e-268e-4cc8-afb0-16b2dec3ffa5'
refresh_options = nil
# Authorization
transaction.auth_by_external_key(external_key,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
# Purchase
transaction.purchase_by_external_key(external_key,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
# Credit
transaction.credit_by_external_key(external_key,
payment_method_id,
user,
reason,
comment,
options,
refresh_options)
accountApi = killbill.AccountApi()
account_external_key = 'sample_external_key'
payment_method_id = '80c7b386-97b2-424c-bb4e-0017f92bc6eb'
# transaction_type could be 'AUTHORIZE', 'PURCHASE' or 'CREDIT'
body = PaymentTransaction(amount=50, transaction_type='AUTHORIZE')
accountApi.process_payment_by_external_key(body,
account_external_key,
payment_method_id=payment_method_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.PaymentTransaction = {amount: 50, transactionType: 'AUTHORIZE'};
api.processPaymentByExternalKey(body,'sample_external_key','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$paymentTransaction = new PaymentTransaction();
$paymentTransaction->setAmount('50');
$paymentTransaction->setTransactionType('AUTHORIZE');
$externalKey = 'sample_external_key';
$apiInstance-> processPaymentByExternalKey($paymentTransaction,$xKillbillCreatedBy,$externalKey,$xKillbillReason,$xKillbillComment);
Request Body
The request body is a JSON string representing the payment transaction. See section Payment Transaction for details on payment transactions.
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| externalKey | string | true | none | the account external key |
| paymentMethodId | string | false | default payment method | payment method ID to use, if not default method |
| controlPluginName | array of strings | false | empty list | list of control plugins, if any |
| pluginProperty | array of strings | false | empty list | list of plugin properties, if any |
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment object, including the generated paymentId.
Payment Method
These endpoints allow you to manage the payment methods for an account. See section Payment Method for details on payment methods.
Add a payment method
Add a payment method for a given Account. The payment method is represented by a plugin that must already be registered with KillBill.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "externalKey": "ExternalKey", "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "pluginName": "__EXTERNAL_PAYMENT__"}' \
"http://127.0.0.1:8080/1.0/kb/accounts/8785164f-b5d7-4da1-9495-33f5105e8d80/paymentMethods"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("6e5d0912-2e56-4511-af77-af054b616696");
String pluginName = "__EXTERNAL_PAYMENT__";
PaymentMethod paymentMethod = new PaymentMethod();
paymentMethod.setPluginName(pluginName);
List<String> NULL_PLUGIN_NAMES = null;
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
//create a payment method
PaymentMethod paymentMethodPP = accountApi.createPaymentMethod(accountId, paymentMethod, NULL_PLUGIN_NAMES, NULL_PLUGIN_PROPERTIES, requestOptions);
//to create a payment method and set it as default use accountApi.createPaymentMethod(accountId, body, isDefault, payAllUnpaidInvoices, controlPluginName, pluginProperty, inputOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
pm = KillBillClient::Model::PaymentMethod.new
pm.account_id = "6e5d0912-2e56-4511-af77-af054b616696"
pm.plugin_name = '__EXTERNAL_PAYMENT__'
pm.plugin_info = nil
is_default = true
pm.create(is_default,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '059ecfb8-6b4d-4a89-9537-63a687e6cf10'
body = PaymentMethod(external_key='ExternalKey', plugin_name='__EXTERNAL_PAYMENT__', plugin_info=None)
accountApi.create_payment_method(account_id,
body,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.PaymentMethod = {externalKey: 'ExternalKey', pluginName: '__EXTERNAL_PAYMENT__'}
api.createPaymentMethod(body,'059ecfb8-6b4d-4a89-9537-63a687e6cf10','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$paymentMethod = new PaymentMethod();
$paymentMethod->setExternalKey("ExternalKey");
$paymentMethod-> setPluginName('__EXTERNAL_PAYMENT__');
$accountID = "059ecfb8-6b4d-4a89-9537-63a687e6cf10";
$apiInstance-> createPaymentMethod($paymentMethod,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);
Request Body
A payment method object specifying accountId and pluginName at the minimum. Please refer to the payment method resource section for more details about the fields.
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| isDefault | boolean | false | false | Choose true to set new payment as default. |
| payAllUnpaidInvoices | boolean | false | false | Choose true to pay all unpaid invoices. |
| controlPluginName | array of strings | false | empty list | list of control plugins, if any |
| pluginProperty | array of strings | false | empty list | list of plugin properties, if any |
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for the payment method, including the generated paymentMethodId.
Retrieve account payment methods
This API retrieves a list of the payment methods that are associated with this account.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
List<PaymentMethod> paymentMethods = accountApi.getPaymentMethodsForAccount(accountId,
NULL_PLUGIN_PROPERTIES,
requestOptions);
payment_method = KillBillClient::Model::PaymentMethod
account_id = "faf239a5-456a-4eb9-aef9-8d2254ef57dc"
with_plugin_info = false
accountPaymentMethods = payment_method.find_all_by_account_id( account_id,
with_plugin_info,
options)
accountApi = killbill.AccountApi()
account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'
accountPaymentMethods = accountApi.get_payment_methods_for_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
const response: AxiosResponse<killbill.PaymentMethod[], any> = await api.getPaymentMethodsForAccount(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
$accountPaymentMethods = $apiInstance-> getPaymentMethodsForAccount($accountID);
Example Response:
[
{
"paymentMethodId": "f835c556-0694-4883-b4c1-d1b6e308409b",
"externalKey": "unknown",
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"isDefault": false,
"pluginName": "__EXTERNAL_PAYMENT__",
"pluginInfo": null,
"auditLogs": []
}
]
Request Body
The request body is a JSON string representing any plugin specific payment information (payment token for exampe).
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| withPluginInfo | boolean | false | false | Choose true to include plugin info. |
| includedDeleted | boolean | false | false | Choose true to include deleted payment methods |
| pluginProperty | array of strings | false | empty list | list of plugin properties, if any |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a list of payment method objects.
Set the default payment method
This API sets an existing payment method to be the default payment method.
HTTP Request
PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods/{paymentMethodId}/setDefault
Example Request:
curl -v \
-X PUT \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods/f835c556-0694-4883-b4c1-d1b6e308409b/setDefault"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
UUID paymentMethodId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
accountApi.setDefaultPaymentMethod(accountId,
paymentMethodId,
NULL_PLUGIN_PROPERTIES,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
payment_method = KillBillClient::Model::PaymentMethod
account_id = 'faf239a5-456a-4eb9-aef9-8d2254ef57dc'
payment_method_id = 'faf239a5-456a-4eb9-aef9-8d2254ef57dc'
payment_method.set_default( payment_method_id,
account_id,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'
payment_method_id = '4f124c0d-cee7-49b1-a181-3b0738c685d7'
accountApi.set_default_payment_method(account_id,
payment_method_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
const paymentMethodId = '4f124c0d-cee7-49b1-a181-3b0738c685d7';
api.setDefaultPaymentMethod(accountID,paymentMethodId,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$paymentMethodID = "4f124c0d-cee7-49b1-a181-3b0738c685d7";
$accountID = "88a5987a-1e1c-47c5-ba95-34ef14db3d46";
$apiInstance-> setDefaultPaymentMethod($accountID,$paymentMethodID,$xKillbillCreatedBy);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| payAllUnpaidInvoices | boolean | false | false | Choose true to pay all unpaid invoices |
| pluginProperty | array of strings | false | empty list | List of plugin properties, if any |
Response
If successful, returns a status code of 204 and an empty body.
Refresh account payment methods
This endpoint is for a rare use case where information for a particular payment method is stored inside the third party gateway, and both Kill Bill core and its payment plugin need to have their view updated.
HTTP Request
PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/paymentMethods/refresh
Example Request:
curl -v \
-X PUT \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/paymentMethods/refresh"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("faf239a5-456a-4eb9-aef9-8d2254ef57dc");
String pluginName = "__EXTERNAL_PAYMENT__";
Map<String, String> NULL_PLUGIN_PROPERTIES = null;
accountApi.refreshPaymentMethods(accountId,
pluginName,
NULL_PLUGIN_PROPERTIES,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
payment_method = KillBillClient::Model::PaymentMethod
account_id = "faf239a5-456a-4eb9-aef9-8d2254ef57dc"
payment_method.refresh( account_id,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'
accountApi.refresh_payment_methods(account_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
api.refreshPaymentMethods(accountID,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$accountID = "88a5987a-1e1c-47c5-ba95-34ef14db3d46";
$apiInstance-> refreshPaymentMethods($accountID,$xKillbillCreatedBy);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| PluginName | array of strings | false | empty list | List of plugins, if any |
| pluginProperty | array of strings | false | empty list | List of plugin properties, if any |
Response
If successful, returns a status code of 204 and an empty body.
Overdue
The system can be configured to move an Account through various overdue (a.k.a. dunning) states when invoices are left unpaid.
Retrieve overdue state for account
Retrieve the current overdue/dunning state for an Account.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/overdue
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/overdue"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("d3a82897-ae72-4a2e-9bca-e3c1fe087f84");
OverdueState result = accountApi.getOverdueAccount(accountId, requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'd3a82897-ae72-4a2e-9bca-e3c1fe087f84'
accountOverdueState = account.overdue(options)
accountApi = killbill.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'
accountOverdueState = accountApi.get_overdue_account(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
const response: AxiosResponse<killbill.OverdueState, any> = await api.getOverdueAccount(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
$accountOverdueState = $apiInstance-> getOverdueAccount($accountID);
Example Response:
{
"name": "__KILLBILL__CLEAR__OVERDUE_STATE__",
"externalMessage": "",
"daysBetweenPaymentRetries": [
8,
8,
8
],
"isDisableEntitlementAndChangesBlocked": false,
"isBlockChanges": false,
"isClearState": true,
"reevaluationIntervalDays": null
}
Query Parameters
None.
Returns
If successful, returns a status code of 200 and an overdue state object.
Blocking State
As part of the entitlement features, Kill Bill provides an abstraction to include BlockingState events into the per Account event stream. The main idea is to allow billing to be modified, such as by pausing a specific subscription or all subscriptions, and to allow modification of the entitlement state, such as by disabling the service associated with a given subscription. The entitlement internal documentation provides some overview of the mechanism. Blocking states are mostly manipulated from inside Kill Bill core, but the functionality is exposed through the API, with the caveat that it is an advanced feature and can lead to unintented behavior if not used properly.
Note that the term BlockingState seems to indicate that something will be blocked, and this can certainly be the case, but not necessarily; actually the attributes
isBlockChange, isBlockEntitlement, isBlockBilling will drive this behavior. These flags are always considered on a per blocking state service, regardless of the state name. For instance, consider the following two scenarios:
- 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
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '{ "stateName": "STATE1", "service": "ServiceStateService", "isBlockChange": false, "isBlockEntitlement": false, "isBlockBilling": false }' \
"http://127.0.0.1:8080/1.0/kb/accounts/10483c3a-3394-4667-8519-0d849e9a8ec2/block"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
BlockingState blockingState = new BlockingState();
blockingState.setStateName("STATE1");
blockingState.setService("ServiceStateService");
blockingState.setIsBlockChange(false);
blockingState.setIsBlockBilling(false);
blockingState.setIsBlockEntitlement(false);
LocalDate requestedDate = new LocalDate("2013-08-01");
Map<String, String> pluginProperty = Collections.emptyMap();
BlockingStates result = accountApi.addAccountBlockingState(accountId,
blockingState,
requestedDate,
pluginProperty,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
account = KillBillClient::Model::Account.new
account.account_id = '864c1418-e768-4cd5-a0db-67537144b685'
state_name = "STATE1"
service = "ServiceStateService"
block_change = false
block_entitlement = false
block_billing = false
requested_date = "2013-08-01"
account.set_blocking_state(state_name,
service,
block_change,
block_entitlement,
block_billing,
requested_date,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
body = BlockingState(state_name='STATE1',
service='ServiceStateService',
is_block_change=False,
is_block_entitlement=False,
is_block_billing=False)
accountApi.add_account_blocking_state(account_id,
body,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.BlockingState = { stateName: 'ACCT_PAUSED',
service: 'billing',
isBlockChange: false,
isBlockEntitlement: false,
isBlockBilling: false
}
api.addAccountBlockingState(body,'07c0cef4-41c5-4606-b2cd-661332cdd41c','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$blockingState = new BlockingState();
$blockingState->setStateName('ACCT_PAUSED');
$blockingState->setService('billing');
$blockingState->setIsBlockChange('false');
$blockingState->setIsBlockBilling('false');
$blockingState->setIsBlockEntitlement('false');
$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";
$apiInstance-> addAccountBlockingState($blockingState,$xKillbillCreatedBy,$accountID);
Request Body
A JSON string representing the blocking state object to be added. For details on this resource see blocking state.
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| requestedDate | string | false | block immediately | Date/DateTime to block an account in yyyy-mm-dd/yyyy-mm-ddThh:mm format. |
| pluginProperty | array of strings | false | empty list | List of plugin properties, if any |
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL for retrieving blocking states for the account.
Retrieve blocking states for account
Retrieves the BlockingState associated with a given resource.
BlockingState can be set at the Account, Bundle or Subscription level.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/block
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/10483c3a-3394-4667-8519-0d849e9a8ec2/block?blockingStateTypes=ACCOUNT"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");
List<BlockingStateType> blockingStateTypes = List.of(BlockingStateType.SUBSCRIPTION_BUNDLE);
List<String> blockingStateSvcs = List.of("service");
BlockingStates blockingStates = accountApi.getBlockingStates(accountId,
blockingStateTypes,
blockingStateSvcs,
AuditLevel.FULL,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'ee6835f0-8347-42d3-958c-9a939383ba28'
blocking_state_types = 'ACCOUNT'
blocking_state_svcs = nil
audit = 'NONE'
accountBlockingStates = account.blocking_states(blocking_state_types,
blocking_state_svcs,
audit,
options)
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
accountBlockingStates = accountApi.get_blocking_states(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
const response: AxiosResponse<killbill.BlockingState[], any> = await api.getBlockingStates(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
$accountBlockingStates = $apiInstance-> getBlockingStates($accountID);
Example Response:
[
{
"blockedId": "10483c3a-3394-4667-8519-0d849e9a8ec2",
"stateName": "STATE1",
"service": "ServiceStateService",
"isBlockChange": false,
"isBlockEntitlement": false,
"isBlockBilling": false,
"effectiveDate": "2018-07-18T14:45:37.000Z",
"type": "ACCOUNT",
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| blockingStateTypes | array of strings | false | retrieve all | blocking state types to retrieve: "SUBSCRIPTION", "SUBSCRIPTION_BUNDLE", "ACCOUNT" |
| blockingStateSvcs | array of strings | false | retrieve all | filter list for blocking state services |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a blocking state object.
Hierarchical Accounts
When using the hierarchical account feature, this API allows you to retrieve
all the child Accounts for a given parent Account.
List child accounts
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/children
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/children"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID parentAccountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");
Boolean accountWithBalance = true; // Will include account balance
Boolean accountWithBalanceAndCBA = true; // Will include account balance and CBA info
Accounts childrenAccounts = accountApi.getChildrenAccounts(parentAccountId,
accountWithBalance,
accountWithBalanceAndCBA,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = "ee6835f0-8347-42d3-958c-9a939383ba28"
with_balance = false
with_balance_and_cba = false
audit = 'NONE'
childrenAccounts = account.children( with_balance,
with_balance_and_cba,
audit,
options)
accountApi = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
childrenAccounts = accountApi.get_children_accounts(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
const response: AxiosResponse<killbill.Account[], any> = await api.getChildrenAccounts(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
$childAccounts = $apiInstance-> getChildrenAccounts($accountID);
Example Response:
[
{
"accountId":"e19c6ab3-1a21-42f2-8ea2-9859c082b093",
"name":"John Doe",
"externalKey":"1522172592-516014",
"email":"[email protected]",
"billCycleDayLocal":0,
"currency":"USD",
"parentAccountId":"01ab962b-3c66-4b17-b391-ffcc9fe51884",
"isPaymentDelegatedToParent":true,
"timeZone":"UTC",
"address1":"7, yoyo road",
"address2":"Apt 5",
"postalCode":"94105",
"company":"Unemployed",
"city":"San Francisco",
"state":"California",
"country":"US",
"locale":"fr_FR",
"auditLogs":[]
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| accountWithBalance | boolean | false | false | if true, returns accountBalance info |
| accountWithBalanceAndCBA | boolean | false | false | if true, returns accountBalance and accountCBA info |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a list of child account objects.
Transfer a given child credit to the parent level
In the context of the Hierarchical Account feature, this allows moving the potential child credit to the parent level.
HTTP Request
PUT http://127.0.0.1:8080/1.0/kb/accounts/{childAccountId}/transferCredit
Example Request:
curl -v \
-X PUT \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/transferCredit"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID childAccountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");
accountApi.transferChildCreditToParent(childAccountId, requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
account = KillBillClient::Model::Account.new
account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'
account.transfer_child_credit(user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
child_account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'
accountApi.transfer_child_credit_to_parent(child_account_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const childAccountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
api.transferChildCreditToParent(childAccountID, 'created_by');
$apiInstance = $client->getAccountApi();
$childAccountID = '88a5987a-1e1c-47c5-ba95-34ef14db3d46';
$apiInstance-> transferChildCreditToParent($childAccountID,$xKillbillCreatedBy);
Query Parameters
None.
Response
If successful, returns a status code of 204 and an empty body.
Custom Fields
Custom fields are {key, value} attributes that can be attached to any customer resource. In particular they can be added to the customer Account. For details on Custom Fields see Custom Field.
Add custom fields to account
Add custom fields to a given Account.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '[ { "objectType": "ACCOUNT", "name": "Test Custom Field", "value": "demo_test_value" }]' \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("15434b45-54c1-4a44-851c-b1f2f7a52f03");
final List<AuditLog> EMPTY_AUDIT_LOGS = Collections.emptyList();
CustomFields customFields = new CustomFields();
customFields.add(new CustomField(null,
accountId,
ObjectType.ACCOUNT,
"Test Custom Field",
"test_value",
EMPTY_AUDIT_LOGS));
accountApi.createAccountCustomFields(accountId,
customFields,
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
account = KillBillClient::Model::Account.new
account.account_id = '15434b45-54c1-4a44-851c-b1f2f7a52f03'
custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'ACCOUNT'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'
account.add_custom_field(custom_field,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
body = CustomField(name='Test Custom Field', value='test_value')
accountApi.create_account_custom_fields(account_id,
[body],
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.CustomField[] = [{ name: 'Test Custom Field', value: 'test_value' }];
api.createAccountCustomFields(body,'8992e146-bfa1-4126-a045-98b844a4adcb','created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$customField = new CustomField();
$customField->setName("Test Custom Field");
$customField->setValue("test_value");
$customFields = array($customField);
$accountID = "8992e146-bfa1-4126-a045-98b844a4adcb";
$apiInstance->createAccountCustomFields($customFields,$xKillbillCreatedBy, $accountID, $xKillbillReason,$xKillbillComment);
Request Body
A list of objects giving the name and value of the custom field, or fields, to be added. For example:
[ { "name": "CF1", "value": "123" } ]
Query Parameters
None.
Response
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL to retrieve the custom fields associated with the account.
Retrieve all custom fields
Retrieves all custom fields attached to various resources owned by the Account.
This endpoint allows you to retrieve all custom fields, or to filter them by type, e.g Subscription.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/allCustomFields
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/allCustomFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("b38de59f-7dd0-447a-a508-9b022b808250");
CustomFields allAccountCustomFields = accountApi.getAllCustomFields(accountId,
ObjectType.ACCOUNT,
AuditLevel.FULL,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
object_type = 'ACCOUNT'
audit = 'NONE'
allCustomFields = account.all_custom_fields(object_type,
audit,
options)
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
allCustomFields = accountApi.get_all_custom_fields(account_id,object_type='ACCOUNT')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
const response: AxiosResponse<killbill.CustomField[], any> = await api.getAllCustomFields(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";
$allCustomFields = $apiInstance->getAllCustomFields($accountID);
Example Response:
[
{
"customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"objectType": "ACCOUNT",
"name": "Test Custom Field",
"value": "test_value",
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| objectType | string | false | retrieve all | type of object |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Possible values for objectType are ACCOUNT, ACCOUNT_EMAIL, BLOCKING_STATES, BUNDLE, CUSTOM_FIELD, INVOICE, PAYMENT, TRANSACTION, INVOICE_ITEM, INVOICE_PAYMENT, SUBSCRIPTION, SUBSCRIPTION_EVENT, SERVICE_BROADCAST, PAYMENT_ATTEMPT, PAYMENT_METHOD, TAG, TAG_DEFINITION, TENANT, or TENANT_KVS.
Response
If successful, returns a status code of 200 and a list of custom field objects
Retrieve account custom fields
Retrieve the custom fields associated with an account
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
List<CustomField> accountCustomFields = accountApi.getAccountCustomFields(accountId,
AuditLevel.NONE,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '59860a0d-c032-456d-a35e-3a48fe8579e5'
audit = 'NONE'
accountCustomFields = account.custom_fields(audit, options)
accountApi = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
accountCustomFields = accountApi.get_account_custom_fields(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
const response: AxiosResponse<killbill.CustomField[], any> = await api.getCustomFields(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";
$accountCustomFields = $apiInstance->getAccountCustomFields($accountID);
Example Response:
[
{
"customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"objectType": "ACCOUNT",
"name": "Test Custom Field",
"value": "test_value",
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a (possibly empty) list of custom field objects
Modify custom fields for an account
Modify the custom fields associated with an account. Note that it is not possible to modify the name of a custom field, it is only possible to modify its value.
HTTP Request
PUT http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customFields
Example Request:
curl -v \
-X PUT \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '[ { "customFieldId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe", "objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "objectType": "ACCOUNT", "name": "Test Custom Field" , "value": "test_modify_value", "auditLogs": [] }]' \
"http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
CustomField customFieldModified = new CustomField();
customFieldModified.setCustomFieldId(customFieldsId);
customFieldModified.setValue("NewValue");
CustomFields customFields = new CustomFields();
customFields.add(customFieldModified);
accountApi.modifyAccountCustomFields(accountId,
customFields,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '59860a0d-c032-456d-a35e-3a48fe8579e5'
custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
custom_field.name = 'Test Modify'
custom_field.value = 'test_modify_value'
account.modify_custom_field(custom_field,
user,
reason,
comment,
options)
account = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
body = CustomField(custom_field_id=custom_field_id,
name='Test Custom Field',
value='test_value')
account.modify_account_custom_fields(account_id,
[body],
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const body: killbill.CustomField = { name: 'Test Custom Field', value: 'test_modify_value' };
api.modifyAccountCustomFields(body,'59860a0d-c032-456d-a35e-3a48fe8579e5','created_by')
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$customField = new CustomField();
$customField->setCustomFieldId('92b90b52-d4ef-47e7-ba4e-614255353a9a');
$customField->setValue("test_modify_value");
$customFields = array($customField);
$accountID = "59860a0d-c032-456d-a35e-3a48fe8579e5";
$apiInstance->modifyAccountCustomFields($customFields,$xKillbillCreatedBy, $accountID, $xKillbillReason,$xKillbillComment);
Request Body
A list of objects specifying the id and the new value for the custom fields to be modified. For example:
[ { "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f", "value": "123" } ]
Although the fieldName and objectType can be specified in the request body, these cannot be modified, only the field value can be modified.
Query Parameters
None.
Returns
If successful, a status code of 204 and an empty body.
Remove custom fields from account
Remove a specified set of custom fields from the account
HTTP Request
DELETE http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/customField
Example Request:
curl -v \
-X DELETE \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields?customField=9913e0f6-b5ef-498b-ac47-60e1626eba8f"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = List.of(customFieldsId);
accountApi.deleteAccountCustomFields(accountId,
customFieldsList,
requestOptions);
custom_field_id = custom_field.custom_field_id
account.remove_custom_field(custom_field_id,
user,
reason,
comment,
options)
account = killbill.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
account.delete_account_custom_fields(account_id,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '8992e146-bfa1-4126-a045-98b844a4adcb';
api.deleteAccountCustomFields(accountID,'created_by')
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$customField = new CustomField();
$accountID = "8992e146-bfa1-4126-a045-98b844a4adcb";
$apiInstance->deleteAccountCustomFields($accountID,$xKillbillCreatedBy);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| customField | string | true | none | Custom field object ID that should be deleted. Multiple custom fields can be deleted by specifying a separate customField parameter corresponding to each field |
Response
If successful, returns a status code of 204 and an empty body.
Tags
This section provides APIs to add tags, to retrieve all tags, to retrieve account tags and to remove tags associated with the account. For more details on tags, see section Tag.
Add tags to account
This API adds one or more tags to an account. The tag definitions must already exist.
HTTP Request
POST http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/tags
Example Request:
curl -v \
-X POST \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
-d '[ "00000000-0000-0000-0000-000000000002"]' \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("f4087a76-9f8a-4893-abbf-c5bb69975d1b");
UUID autoPayOffTagId = UUID.fromString("00000000-0000-0000-0000-000000000001");
Tags result = accountApi.createAccountTags(accountId,
List.of(autoPayOffTagId),
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
account = KillBillClient::Model::Account.new
account.account_id = 'f4087a76-9f8a-4893-abbf-c5bb69975d1b'
tag_name = 'TEST'
account.add_tag(tag_name,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tagDefIds = ["00000000-0000-0000-0000-000000000002"]
accountApi.create_account_tags(account_id,
tagDefIds,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const tags = ['00000000-0000-0000-0000-000000000002'];
api.createAccountTags(tags,'b0da8392-49ba-43f2-8fac-3f9f85b8ff61','created_by')
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$tags = ['00000000-0000-0000-0000-000000000002'];
$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";
$apiInstance->createAccountTags($tags,$xKillbillCreatedBy,$accountID,$xKillbillReason,$xKillbillComment);
Request Body
A JSON array containing one or more tag definition ids to be added as user tags.
Query Parameters
None.
Returns
If successful, returns a 201 status code. In addition, a Location header is returned giving the URL to retrieve the tags associated with the account.
Retrieve all tags
Retrieves all tags attached to resources owned by this Account. This API allows you to retrieve all tags, or only tags attached to a specified resource type.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/allTags
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/allTags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("ee6835f0-8347-42d3-958c-9a939383ba28");
Tags allAccountTags = accountApi.getAllTags(accountId,
ObjectType.ACCOUNT,
requestOptions);
accountApi = killbill.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
allAccountTags = accountApi.get_all_tags(account_id)
account = KillBillClient::Model::Account.new
account.account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
object_type = 'ACCOUNT'
included_deleted = false
audit = 'NONE'
allTags = account.all_tags(object_type,
included_deleted,
audit,
options)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '07c0cef4-41c5-4606-b2cd-661332cdd41c';
const response: AxiosResponse<any> = await api.getAllTags(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";
$allTags = $apiInstance->getAllTags($accountID);
Example Response:
[
{
"tagId": "0f7c5837-1ed9-41ab-b391-9ef7ea4ab049",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"tagDefinitionId": "00000000-0000-0000-0000-000000000002",
"tagDefinitionName": "AUTO_INVOICING_OFF",
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| objectType | string | false | all object types | choose type of object |
| includedDeleted | boolean | false | false | choose true to include deleted tags |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Possible values for objectType are ACCOUNT, ACCOUNT_EMAIL, BLOCKING_STATES, BUNDLE, CUSTOM_FIELD, INVOICE, PAYMENT, TRANSACTION, INVOICE_ITEM, INVOICE_PAYMENT, SUBSCRIPTION, SUBSCRIPTION_EVENT, SERVICE_BROADCAST, PAYMENT_ATTEMPT, PAYMENT_METHOD, TAG, TAG_DEFINITION, TENANT, or TENANT_KVS.
Response
If successful, returns a status code of 200 and a list of tag objects.
Retrieve account tags
Retrieve all tags attached to this account itself.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/tags
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");
Boolean includedDeleted = false; // Will not include deleted tags
List<Tag> tags1 = accountApi.getAccountTags(accountId,
includedDeleted,
AuditLevel.FULL,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'
included_deleted = false
audit = 'NONE'
accountTags = account.tags(included_deleted,
audit,
options)
accountApi = killbill.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
accountTags = accountApi.get_account_tags(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
const response: AxiosResponse<any> = await api.getAccountTags(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "07c0cef4-41c5-4606-b2cd-661332cdd41c";
$accountTags = $apiInstance->getAccountTags($accountID);
Example Response:
[
{
"tagId": "0f7c5837-1ed9-41ab-b391-9ef7ea4ab049",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"tagDefinitionId": "00000000-0000-0000-0000-000000000002",
"tagDefinitionName": "AUTO_INVOICING_OFF",
"auditLogs": []
}
]
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| includedDeleted | boolean | false | false | choose true to include deleted tags |
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a list of tag objects.
Remove tags from account
This API removes a list of tags attached to an account.
HTTP Request
DELETE http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/tags
Example Request:
curl -v \
-X DELETE \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "X-Killbill-CreatedBy: demo" \
-H "X-Killbill-Reason: demo" \
-H "X-Killbill-Comment: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags?tagDef=00000000-0000-0000-0000-000000000002"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e659f0f3-745c-46d5-953c-28fe9282fc7d");
UUID autoPayOffId = UUID.fromString("00000000-0000-0000-0000-000000000001");
accountApi.deleteAccountTags(accountId,
List.of(autoPayOffId),
requestOptions);
user = 'user'
reason = 'reason'
comment = 'comment'
account = KillBillClient::Model::Account.new
account.account_id = 'e659f0f3-745c-46d5-953c-28fe9282fc7d'
tag_name = 'TEST'
account.remove_tag(tag_name,
user,
reason,
comment,
options)
accountApi = killbill.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tagDefIds = ["00000000-0000-0000-0000-000000000002"]
accountApi.delete_account_tags(account_id,
tag_def=tagDefIds,
created_by='demo',
reason='reason',
comment='comment')
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
api.deleteAccountTags(accountID,'created_by');
$apiInstance = $client->getAccountApi();
$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";
$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";
$apiInstance->deleteAccountTags($accountID,$xKillbillCreatedBy,$xKillbillCreatedBy,$xKillbillComment);
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| tagDef | array of string | true | none | A tag definition ID identifying the tag that should be removed. Multiple tags can be deleted by specifying a separate tagDef parameter corresponding to each tag. |
Response
If successful, returns a status code of 204 and an empty body.
Audit Logs
Audit logs provide a record of events that occur involving various specific resources. For details on audit logs see Audit and History.
Retrieve audit logs
Retrieve a list of audit log records showing events that occurred involving changes to any resource associated with the specified account. History information (a copy of the full resource object) is not included.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/auditLogs
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/auditLogs"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("e9432491-6558-4007-85ef-cdae171d240c");
AuditLogs auditLogsJson = accountApi.getAccountAuditLogs(accountId,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = '4e4d8acd-c97d-447a-814b-28f995a9106c'
auditLogs = account.audit(options)
accountApi = killbill.AccountApi()
account_id = '4e4d8acd-c97d-447a-814b-28f995a9106c'
auditLogs = accountApi.get_account_audit_logs(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountAuditLogs(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";
$accountAuditLogs = $apiInstance->getAccountAuditLogs($accountID);
Example Response:
[
{
"changeType": "INSERT",
"changeDate": "2018-07-17T15:02:45.000Z",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "bca75b40-ffa3-41f8-9fde-06f83ee303e8",
"history": null
},
{
"changeType": "UPDATE",
"changeDate": "2018-07-17T18:46:47.000Z",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "9a61a1e6-78f3-43d3-addf-e7ada180b23d",
"history": null
},
{
"changeType": "UPDATE",
"changeDate": "2018-07-17T18:48:37.000Z",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "0c41a04d-4037-4fa9-af71-dfe54af4d3ae",
"history": null
},
{
"changeType": "INSERT",
"changeDate": "2018-07-17T19:07:25.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "c9b9ab11-14b1-41b5-8371-1c425f273336",
"history": null
},
{
"changeType": "UPDATE",
"changeDate": "2018-07-17T19:26:46.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "fd26b216-deb2-43d4-b748-dec8e9917ada",
"history": null
},
{
"changeType": "DELETE",
"changeDate": "2018-07-17T20:02:01.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "48e24ca0-1cfe-41c3-85e7-0ff0d51679fe",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "0d5c8db7-974f-47e0-9332-5d9625f72155",
"history": null
}
]
Query Parameters
None.
Response
If successful, returns a status code of 200 and a list of audit logs.
Retrieve account audit logs with history
Retrieve a list of audit log records showing events that occurred involving changes to the specified account itself. History information (a copy of the full account object) is included with each record.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/auditLogsWithHistory
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("ecbff3be-3cbf-4e1d-ae05-d323d4597877");
List<AuditLog> auditLogWithHistories = accountApi.getAccountAuditLogsWithHistory(accountId,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
auditLogsWithHistory = account.audit_logs_with_history(options)
accountApi = killbill.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
auditLogsWithHistory = accountApi.get_account_audit_logs_with_history(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61';
const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountAuditLogsWithHistory(accountID);
$apiInstance = $client->getAccountApi();
$accountID = "b0da8392-49ba-43f2-8fac-3f9f85b8ff61";
$accountAuditLogs = $apiInstance->getAccountAuditLogsWithHistory($accountID);
Example Response:
[
{
"changeType": "INSERT",
"changeDate": "2018-07-17T15:02:45.000Z",
"objectType": "ACCOUNT",
"objectId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "bca75b40-ffa3-41f8-9fde-06f83ee303e8",
"history": {
"id": null,
"createdDate": "2018-07-17T15:02:45.000Z",
"updatedDate": "2018-07-17T15:02:45.000Z",
"recordId": 120,
"accountRecordId": 120,
"tenantRecordId": 101,
"externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"email": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"name": "John Doe",
"firstNameLength": null,
"currency": "USD",
"parentAccountId": null,
"isPaymentDelegatedToParent": false,
"billingCycleDayLocal": 0,
"paymentMethodId": null,
"referenceTime": "2018-07-17T15:02:45.000Z",
"timeZone": "UTC",
"locale": null,
"address1": null,
"address2": null,
"companyName": null,
"city": null,
"stateOrProvince": null,
"country": null,
"postalCode": null,
"phone": null,
"notes": null,
"migrated": null,
"tableName": "ACCOUNT",
"historyTableName": "ACCOUNT_HISTORY"
}
}
]
Query Parameters
None.
Response
If successful, returns a status code of 200 and a list of audit logs.
Retrieve account email audit logs with history
Retrieve a list of audit log records showing events that occurred involving changes to a specified account email. History information (a copy of the full email object) is included with each record.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/emails/{accountEmailId}/auditLogsWithHistory
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails/aa2a5614-88d9-4ec3-a042-a4771bd66670/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("873c26ef-a3fa-4942-b2f5-549b51f20b1a");
UUID accountEmailId = UUID.fromString("f637441d-855e-4bf5-bac1-6426bdb116d6");
List<AuditLog> result = accountApi.getAccountEmailAuditLogsWithHistory(accountId,
accountEmailId,
requestOptions);
account = KillBillClient::Model::Account.new
account.account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
account_email_id = 'a4627e89-a73b-4167-a7ba-92a2881eb3c4'
emailAuditLogsWithHistory = account.email_audit_logs_with_history(account_email_id, options)
accountApi = killbill.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
account_email_id = 'bb390282-6757-4f4f-8dd5-456abd9f30b2'
emailAuditLogsWithHistory = accountApi.get_account_email_audit_logs_with_history(account_id,
account_email_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda';
const accountEmailID = 'bb390282-6757-4f4f-8dd5-456abd9f30b2';
const response: AxiosResponse<killbill.AuditLog[], any> = await api.getAccountEmailAuditLogsWithHistory(accountID,accountEmailID);
$apiInstance = $client->getAccountApi();
$accountID = "c62d5f6d-0b57-444d-bf9b-dd23e781fbda";
$accountEmailID = 'bb390282-6757-4f4f-8dd5-456abd9f30b2';
$accountEmailAuditLogs = $apiInstance->getAccountEmailAuditLogsWithHistory($accountID,$accountEmailID);
Example Response:
[
{
"changeType": "INSERT",
"changeDate": "2018-07-18T15:13:22.000Z",
"objectType": "ACCOUNT_EMAIL",
"objectId": "aa2a5614-88d9-4ec3-a042-a4771bd66670",
"changedBy": "demo",
"reasonCode": "demo",
"comments": "demo",
"userToken": "927546eb-3431-4bcf-8fcc-1787d2130772",
"history": {
"id": null,
"createdDate": "2018-07-18T15:13:22.000Z",
"updatedDate": "2018-07-18T15:13:22.000Z",
"recordId": 1,
"accountRecordId": 120,
"tenantRecordId": 101,
"accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
"email": "[email protected]",
"isActive": true,
"tableName": "ACCOUNT_EMAIL",
"historyTableName": "ACCOUNT_EMAIL_HISTORY"
}
}
]
Query Parameters
None.
Response
If successful, returns a status code of 200 and a list of account email audit records, including history (copies of the complete record).
Retrieve blocking state audit logs with history
Retrieves the audit logs for a specific blocking state, given the blocking state id. History records (blocking state objects) are included.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/block/{blockingId}/auditLogsWithHistory
See section Account Blocking State for an introduction to blocking states.
Example Request:
curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/block/763fd113-1b9b-4d0d-be01-6ee56d3879f5/auditLogsWithHistory"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID blockingId = UUID.fromString("0997b953-2b3a-4dc5-ad01-c38911662923");
AuditLogs result = accountApi.getBlockingStateAuditLogsWithHistory(blockingId, requestOptions);
const api: killbill.AccountApi = new killbill.AccountApi(config);
const blockingId = '0997b953-2b3a-4dc5-ad01-c38911662923';
const response: AxiosResponse<killbill.AuditLog[], any> = await api.getBlockingStateAuditLogsWithHistory(blockingId);
$apiInstance = $client->getAccountApi();
$blockingId = '0997b953-2b3a-4dc5-ad01-c38911662923';
$blockingStateAuditLogs = $apiInstance->getBlockingStateAuditLogsWithHistory($blockingId);
Example Response:
[
{
"changeType": "INSERT",
"changeDate": "2019-02-22T22:38:10.000Z",
"objectType": "BLOCKING_STATES",
"objectId": "763fd113-1b9b-4d0d-be01-6ee56d3879f5",
"changedBy": "admin",
"reasonCode": null,
"comments": null,
"userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
"history": {
"id": null,
"createdDate": "2019-02-22T22:38:10.000Z",
"updatedDate": "2019-02-22T22:38:10.000Z",
"recordId": 1326,
"accountRecordId": 10,
"tenantRecordId": 1,
"blockableId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
"type": "SUBSCRIPTION",
"state": "ENT_STARTED",
"service": "entitlement-service",
"blockChange": false,
"blockEntitlement": false,
"blockBilling": false,
"effectiveDate": "2019-02-22T22:38:10.000Z",
"isActive": true,
"tableName": "BLOCKING_STATES",
"historyTableName": "BLOCKING_STATES",
"active": true
}
}
]
Query Parameters
None.
Response
If successful, returns a status code of 200 and a list of blocking state audit logs with history.
Retrieve account timeline
This API retrieves the chronological set of events that occurred concerning a specific Account.
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/accounts/{accountId}/timeline
Example Request:
curl -v \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/timeline"
import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;
UUID accountId = UUID.fromString("16364ac4-2a77-4444-b2d8-e980c37a8954");
Boolean parallel = false;
AccountTimeline timeline = accountApi.getAccountTimeline(accountId,
parallel,
AuditLevel.NONE,
requestOptions);
account_id = account.account_id
audit = 'MINIMAL'
KillBillClient::Model::AccountTimeline.timeline(account_id,
audit,
options)
accountApi = killbill.AccountApi()
account_id = '43488882-1777-460c-bc32-e375e67d09cf'
accountTimeline = accountApi.get_account_timeline(account_id)
const api: killbill.AccountApi = new killbill.AccountApi(config);
const accountID = '43488882-1777-460c-bc32-e375e67d09cf';
const response: AxiosResponse<killbill.AccountTimeline, any> = await api.getAccountTimeline(accountID);
$apiInstance = $client->getAccountApi();
$accountID = '43488882-1777-460c-bc32-e375e67d09cf';
$accountTimeline = $apiInstance->getAccountTimeline($accountID);
Example Response:
{
"account": {
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"name": "25thAuGCus6",
"firstNameLength": null,
"externalKey": "25thAuGCus6",
"email": null,
"billCycleDayLocal": 1,
"currency": "USD",
"parentAccountId": null,
"isPaymentDelegatedToParent": false,
"paymentMethodId": null,
"referenceTime": "2023-08-25T16:28:43.000Z",
"timeZone": "Etc/UTC",
"address1": null,
"address2": null,
"postalCode": null,
"company": null,
"city": null,
"state": null,
"country": "US",
"locale": "en_US",
"phone": null,
"notes": null,
"isMigrated": false,
"accountBalance": null,
"accountCBA": null,
"auditLogs": []
},
"bundles": [
{
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"externalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"subscriptions": [
{
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"bundleExternalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"subscriptionId": "cc608e24-509e-4b99-9519-2eeef67c20a2",
"externalKey": "cc608e24-509e-4b99-9519-2eeef67c20a2",
"startDate": "2023-01-01T16:28:43.000Z",
"productName": "prodA",
"productCategory": "BASE",
"billingPeriod": "MONTHLY",
"phaseType": "EVERGREEN",
"priceList": "DEFAULT",
"planName": "Standard-monthly",
"state": "ACTIVE",
"sourceType": "NATIVE",
"cancelledDate": null,
"chargedThroughDate": "2023-09-01",
"billingStartDate": "2023-01-01T16:28:43.000Z",
"billingEndDate": null,
"billCycleDayLocal": 1,
"quantity": 1,
"events": [
{
"eventId": "23088e1e-646c-4ce7-ad45-9c4369ef223a",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-01-01T16:28:43.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
},
{
"eventId": "1b122b2b-eea4-4a6b-80a2-f9ae2a336fad",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-01-01T16:28:43.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
},
{
"eventId": "368581ee-cf14-4b81-9c34-c06adb5dbbcf",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-08-28T16:55:37.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "SERVICE_STATE_CHANGE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "ServiceStateService",
"serviceStateName": "STATE1",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
}
],
"priceOverrides": null,
"prices": [
{
"planName": "Standard-monthly",
"phaseName": "Standard-monthly-evergreen",
"phaseType": "EVERGREEN",
"fixedPrice": null,
"recurringPrice": 100,
"usagePrices": []
}
],
"auditLogs": []
}
],
"timeline": {
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleId": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"externalKey": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"events": [
{
"eventId": "23088e1e-646c-4ce7-ad45-9c4369ef223a",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-01-01T16:28:43.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "START_ENTITLEMENT",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "entitlement-service",
"serviceStateName": "ENT_STARTED",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
},
{
"eventId": "1b122b2b-eea4-4a6b-80a2-f9ae2a336fad",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-01-01T16:28:43.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "START_BILLING",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "billing-service",
"serviceStateName": "START_BILLING",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
},
{
"eventId": "368581ee-cf14-4b81-9c34-c06adb5dbbcf",
"billingPeriod": "MONTHLY",
"effectiveDate": "2023-08-28T16:55:37.000Z",
"catalogEffectiveDate": "2023-08-24T16:24:23.000Z",
"plan": "Standard-monthly",
"product": "prodA",
"priceList": "DEFAULT",
"eventType": "SERVICE_STATE_CHANGE",
"isBlockedBilling": false,
"isBlockedEntitlement": false,
"serviceName": "ServiceStateService",
"serviceStateName": "STATE1",
"phase": "Standard-monthly-evergreen",
"auditLogs": []
}
],
"auditLogs": []
},
"auditLogs": []
}
],
"invoices": [
{
"amount": 100,
"currency": "USD",
"status": "COMMITTED",
"creditAdj": 0,
"refundAdj": 0,
"invoiceId": "2645c1f3-1d72-41a7-8cdb-3dca43340af6",
"invoiceDate": "2023-08-25",
"targetDate": "2023-01-01",
"invoiceNumber": "17859",
"balance": 0,
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"credits": [],
"items": null,
"trackingIds": null,
"isParentInvoice": false,
"parentInvoiceId": null,
"parentAccountId": null,
"auditLogs": []
},
{
"amount": 100,
"currency": "USD",
"status": "COMMITTED",
"creditAdj": 0,
"refundAdj": 0,
"invoiceId": "e8dbe200-0738-4317-9c74-581696a0b4e9",
"invoiceDate": "2023-08-25",
"targetDate": "2023-02-01",
"invoiceNumber": "17860",
"balance": 0,
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"credits": [],
"items": null,
"trackingIds": null,
"isParentInvoice": false,
"parentInvoiceId": null,
"parentAccountId": null,
"auditLogs": []
},
{
"amount": 100,
"currency": "USD",
"status": "COMMITTED",
"creditAdj": 0,
"refundAdj": 0,
"invoiceId": "72662545-787c-4e9a-90af-4ac728392c35",
"invoiceDate": "2023-08-25",
"targetDate": "2023-03-01",
"invoiceNumber": "17861",
"balance": 0,
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"credits": [],
"items": null,
"trackingIds": null,
"isParentInvoice": false,
"parentInvoiceId": null,
"parentAccountId": null,
"auditLogs": []
},
{
"amount": 500,
"currency": "USD",
"status": "COMMITTED",
"creditAdj": 0,
"refundAdj": 0,
"invoiceId": "3a5d2748-88df-4f3f-bb60-49e8fbce1c0a",
"invoiceDate": "2023-08-25",
"targetDate": "2023-08-25",
"invoiceNumber": "17862",
"balance": 0,
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"bundleKeys": "736d6b5a-a6f8-4c60-a0ec-43782b4cd1b4",
"credits": [],
"items": null,
"trackingIds": null,
"isParentInvoice": false,
"parentInvoiceId": null,
"parentAccountId": null,
"auditLogs": []
}
],
"payments": [
{
"targetInvoiceId": "2645c1f3-1d72-41a7-8cdb-3dca43340af6",
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"paymentId": "555d80f8-abdf-4b25-9994-ac605b012ccb",
"paymentNumber": "41",
"paymentExternalKey": "555d80f8-abdf-4b25-9994-ac605b012ccb",
"authAmount": 0,
"capturedAmount": 0,
"purchasedAmount": 100,
"refundedAmount": 0,
"creditedAmount": 0,
"currency": "USD",
"paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
"transactions": [
{
"transactionId": "57857941-6956-413d-ac62-99af982d6f41",
"transactionExternalKey": "57857941-6956-413d-ac62-99af982d6f41",
"paymentId": "555d80f8-abdf-4b25-9994-ac605b012ccb",
"paymentExternalKey": "555d80f8-abdf-4b25-9994-ac605b012ccb",
"transactionType": "PURCHASE",
"amount": 100,
"currency": "USD",
"effectiveDate": "2023-08-28T16:27:44.000Z",
"processedAmount": 100,
"processedCurrency": "USD",
"status": "SUCCESS",
"gatewayErrorCode": null,
"gatewayErrorMsg": null,
"firstPaymentReferenceId": null,
"secondPaymentReferenceId": null,
"properties": null,
"auditLogs": []
}
],
"paymentAttempts": null,
"auditLogs": []
},
{
"targetInvoiceId": "e8dbe200-0738-4317-9c74-581696a0b4e9",
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"paymentId": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
"paymentNumber": "42",
"paymentExternalKey": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
"authAmount": 0,
"capturedAmount": 0,
"purchasedAmount": 100,
"refundedAmount": 0,
"creditedAmount": 0,
"currency": "USD",
"paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
"transactions": [
{
"transactionId": "60c4ffe7-f67c-456d-955d-6d35d2cd3fd2",
"transactionExternalKey": "60c4ffe7-f67c-456d-955d-6d35d2cd3fd2",
"paymentId": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
"paymentExternalKey": "2252f1cf-8cff-43b9-8d4b-472be14b79a2",
"transactionType": "PURCHASE",
"amount": 100,
"currency": "USD",
"effectiveDate": "2023-08-28T16:27:44.000Z",
"processedAmount": 100,
"processedCurrency": "USD",
"status": "SUCCESS",
"gatewayErrorCode": null,
"gatewayErrorMsg": null,
"firstPaymentReferenceId": null,
"secondPaymentReferenceId": null,
"properties": null,
"auditLogs": []
}
],
"paymentAttempts": null,
"auditLogs": []
},
{
"targetInvoiceId": "72662545-787c-4e9a-90af-4ac728392c35",
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"paymentId": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
"paymentNumber": "43",
"paymentExternalKey": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
"authAmount": 0,
"capturedAmount": 0,
"purchasedAmount": 100,
"refundedAmount": 0,
"creditedAmount": 0,
"currency": "USD",
"paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
"transactions": [
{
"transactionId": "aee6788b-526b-4c15-a943-b46bb9fe3ecf",
"transactionExternalKey": "aee6788b-526b-4c15-a943-b46bb9fe3ecf",
"paymentId": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
"paymentExternalKey": "55ef60c6-d89e-4d0b-aefd-42c13ce410b6",
"transactionType": "PURCHASE",
"amount": 100,
"currency": "USD",
"effectiveDate": "2023-08-28T16:27:44.000Z",
"processedAmount": 100,
"processedCurrency": "USD",
"status": "SUCCESS",
"gatewayErrorCode": null,
"gatewayErrorMsg": null,
"firstPaymentReferenceId": null,
"secondPaymentReferenceId": null,
"properties": null,
"auditLogs": []
}
],
"paymentAttempts": null,
"auditLogs": []
},
{
"targetInvoiceId": "3a5d2748-88df-4f3f-bb60-49e8fbce1c0a",
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"paymentId": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
"paymentNumber": "44",
"paymentExternalKey": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
"authAmount": 0,
"capturedAmount": 0,
"purchasedAmount": 500,
"refundedAmount": 0,
"creditedAmount": 0,
"currency": "USD",
"paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
"transactions": [
{
"transactionId": "3f424634-7207-48fc-8de5-8bf2de229984",
"transactionExternalKey": "3f424634-7207-48fc-8de5-8bf2de229984",
"paymentId": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
"paymentExternalKey": "47d0a7c2-bffb-4c3a-b464-df17825260a0",
"transactionType": "PURCHASE",
"amount": 500,
"currency": "USD",
"effectiveDate": "2023-08-28T16:27:44.000Z",
"processedAmount": 500,
"processedCurrency": "USD",
"status": "SUCCESS",
"gatewayErrorCode": null,
"gatewayErrorMsg": null,
"firstPaymentReferenceId": null,
"secondPaymentReferenceId": null,
"properties": null,
"auditLogs": []
}
],
"paymentAttempts": null,
"auditLogs": []
},
{
"targetInvoiceId": null,
"accountId": "ccf4e359-6b2b-4e26-9c3c-89e391b8fe85",
"paymentId": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
"paymentNumber": "45",
"paymentExternalKey": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
"authAmount": 50,
"capturedAmount": 0,
"purchasedAmount": 0,
"refundedAmount": 0,
"creditedAmount": 0,
"currency": "USD",
"paymentMethodId": "1f6c1080-74a6-4b52-bce1-2ca954086f72",
"transactions": [
{
"transactionId": "8c890167-62cc-4a13-b724-93b8274da3d5",
"transactionExternalKey": "8c890167-62cc-4a13-b724-93b8274da3d5",
"paymentId": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
"paymentExternalKey": "a3dd2264-b00f-45e9-aa5a-7a1f357aa786",
"transactionType": "AUTHORIZE",
"amount": 50,
"currency": "USD",
"effectiveDate": "2023-08-28T16:34:34.000Z",
"processedAmount": 50,
"processedCurrency": "USD",
"status": "SUCCESS",
"gatewayErrorCode": null,
"gatewayErrorMsg": null,
"firstPaymentReferenceId": null,
"secondPaymentReferenceId": null,
"properties": null,
"auditLogs": []
}
],
"paymentAttempts": null,
"auditLogs": []
}
]
}
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| audit | string | false | "NONE" | Level of audit information to return: "NONE", "MINIMAL", or "FULL" |
Response
If successful, returns a status code of 200 and a complete account record including: the account object; bundles with subscriptions and timelines giving all events; invoices; and payments including payment attempts.