Using Kill Bill APIs

Introduction

Kill Bill offers a set of HTTP APIs, commonly called REST APIs, that use the HTTP verbs POST, GET, PUT, DELETE to invoke Create, Read, Update and Delete (CRUD) operations, and that use HTTP response codes to indicate errors. These APIs enable the management of Kill Bill resources -- e.g Account -- through the use of JSON input and output.

Kill Bill also offers a set of java APIs that can be used by plugins to make requests, and a set of java plugin APIs for Kill Bill core to interact with the plugins. These apis are beyond the scope of this documentation.

API client libraries

Official libraries for the Kill Bill API are available in several languages, including Java, Php, Python, Ruby, Node, and Go. Community-supported libraries such as .NET are also available. Note that code examples for Curl, Java, Ruby and Python are shown in the right-hand column of this document.

In the following documentation, we assume you have a Kill Bill server instance running on 127.0.0.1 on port 8080. It is straightforward to substitute a different IP address or port number if necessary.

Kill Bill supports the https protocol, but here all examples are shown using http.

//
// You can find the java client on github: https://github.com/killbill/killbill-client-java
//

#
# You can find the ruby client on github: https://github.com/killbill/killbill-client-ruby
#

The description of the API in this documentation is limited to the most common use cases and does not include advanced features that we have crafted over the years from all the use cases we have seen from our users.

For questions about API use, or to report bugs, you can subscribe to the Kill Bill user mailing list.

Authentication and RBAC

In order to make API calls, one needs to authenticate each request by passing an HTTP Authorization header and by following the HTTP Basic authentication scheme.

Depending on how the system has been configured, the authentication mechanism can happen using different options -- some or all at the same time:

• Flat file configuration
• Database configuration
• LDAP configuration
• OKTA configuration

The system also supports configuring roles and permissions, to restrict user access to certain resources and operations. The permissions are quite granular and are defined here

Multi-Tenancy

Kill Bill has been designed from the ground up to run multiple logical instances on the same set of servers and databases. This allows different customer data sets to be cleanly separated. Another common use case is to configure both a production tenant and a test tenant, the latter being used for test requests during deployment and for sanity after deployment.

Each API call requires the tenant being used to be identified, through the use of 2 HTTP headers:

• X-Killbill-ApiKey: The API key associated with the tenant. This value is stored in clear in the database.
• X-Killbill-ApiSecret: The API secret associated with the tenant. This value is hashed and stored along with the salt in the database

Specifying the basic authentication headers and multi-tenancy headers:

curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
...

KillBillHttpClient killBillHttpClient = new KillBillHttpClient(String.format("http://%s:%d", "127.0.0.1", 8080),
                                                               username,
                                                               password,
                                                               apiKey,
                                                               apiSecret,
                                                               null,
                                                               null,
                                                               1000,
                                                               5000,
                                                               5000);

AccountApi accountApi = new AccountApi(killBillHttpClient);
AdminApi adminApi = new AdminApi(killBillHttpClient);
BundleApi bundleApi = new BundleApi(killBillHttpClient);
CatalogApi catalogApi = new CatalogApi(killBillHttpClient);
CreditApi creditApi = new CreditApi(killBillHttpClient);
CustomFieldApi customFieldApi = new CustomFieldApi(killBillHttpClient);
ExportApi exportApi = new ExportApi(killBillHttpClient);
InvoiceApi invoiceApi = new InvoiceApi(killBillHttpClient);
InvoiceItemApi invoiceItemApi = new InvoiceItemApi(killBillHttpClient);
InvoicePaymentApi invoicePaymentApi = new InvoicePaymentApi(killBillHttpClient);
NodesInfoApi nodesInfoApi = new NodesInfoApi(killBillHttpClient);
OverdueApi overdueApi = new OverdueApi(killBillHttpClient);
PaymentApi paymentApi = new PaymentApi(killBillHttpClient);
PaymentGatewayApi paymentGatewayApi = new PaymentGatewayApi(killBillHttpClient);
PaymentMethodApi paymentMethodApi = new PaymentMethodApi(killBillHttpClient);
PaymentTransactionApi paymentTransactionApi = new PaymentTransactionApi(killBillHttpClient);
PluginInfoApi pluginInfoApi = new PluginInfoApi(killBillHttpClient);
SecurityApi securityApi = new SecurityApi(killBillHttpClient);
SubscriptionApi subscriptionApi = new SubscriptionApi(killBillHttpClient);
TagApi tagApi = new TagApi(killBillHttpClient);
TagDefinitionApi tagDefinitionApi = new TagDefinitionApi(killBillHttpClient);
TenantApi tenantApi = new TenantApi(killBillHttpClient);
UsageApi usageApi = new UsageApi(killBillHttpClient);

// Request Options example
String createdBy = "me";
String reason = "Going through my first tutorial";
String comment = "I like it!";

String apiKey = "bob";
String apiSecret = "lazar";


RequestOptions requestOptions = RequestOptions.builder()
                                              .withCreatedBy(createdBy)
                                              .withReason(reason)
                                              .withComment(comment)
                                              .withQueryParams(queryParams)
                                              .withTenantApiKey(apiKey)
                                              .withTenantApiSecret(apiSecret)
                                              .build();

require 'killbill_client'

KillBillClient.url = 'http://127.0.0.1:8080'

# Multi-tenancy and RBAC credentials
options = {
  :username => 'admin',
  :password => 'password',
  :api_key => 'bob',
  :api_secret => 'lazar'
}

# Audit log data
user = 'me'
reason = 'Going through my first tutorial'
comment = 'I like it!'

# Start using....

# Edit file: configuration.py, lines:50-62

# Default Base url
self.host = "http://localhost:8080"
# Temp file folder for downloading files
self.temp_folder_path = None

# Authentication Settings
# dict to store API key(s)
self.api_key = {}
# dict to store API prefix (e.g. Bearer)
self.api_key_prefix = {}
# Username for HTTP basic authentication
self.username = "admin"
# Password for HTTP basic authentication
self.password = "password"

####################################################

# Basic example using the client
exampleApi = killbill.api.ExampleApi()
body = Example(name='John', last_name = 'Doe')
created_by = 'me'
api_key = 'bob'
api_secret = 'lazar'

exampleApi.create(body, 
                  created_by, 
                  api_key, 
                  api_secret)

Resource IDs and External Keys

When a new resource is created, there are 2 IDS associated with it. Kill Bill will allocate a unique ID, and the user of the API will also be able to associate its own unique key, called the external key. The external key is used for 2 scenarios:

• ID Mapping: Typically an external key can be passed to create a mapping between the ID generated by Kill Bill and a known key for this resource
• Idempotency: Kill Bill ensures that each external key is unique, so if an API call times out, it can be safely retried with the same external key. The second request would only succeed if the first one did not complete. This ensures idempotency of the call, since the external key is unique per tenant and across all resources.

Pagination

Besides the traditional CRUD APIs associated with each resource, we also offer pagination APIs to allow the listing of per-tenant resources, such as all Accounts for a given tenant. These APIs include an offset and a limit, provided as query parameters, to allow the listing of all resources of a given type, on a page by page basis. In addition to the json list, each response will also include the following http headers:

• X-Killbill-Pagination-CurrentOffset : The offest of the first record in the returned list
• X-Killbill-Pagination-NextOffset : The header will only be present if there are additional entries to return and would include the next offset
• X-Killbill-Pagination-TotalNbRecords : The total number of records
• X-Killbill-Pagination-NextPageUri : The uri that can be used to retrieve the next page.

Audit and History

Every api in Kill Bill that creates, or modifies state will create an audit log record to track who made the change. In addition, we also allow the record to specify why this change was made. This information is passed for every POST, PUT, and DELETE request and relies on special HTTP headers:

• X-Killbill-CreatedBy : Mandatory header to track who made the change.
• X-Killbill-Reason : Optional header to track the reason; typically one would use a special reason code -- e.g COURTESY_REFUND.
• X-Killbill-Comment : Optional header to track the metadata; typically one would add more information -- e.g 'Good old faithful customer'.

In addition to the audit log, Kill Bill also records the history of the changes. For instance updating the billing addess of a customer would create an additonal row to track the change and link it to the audit log. The audit query parameter can take the following values:

• NONE [Default]: No audit log is beeing returned.
• MINIMAL : Only rows associated to inserts are being returned, but no updates.
• FULL : Everything is being returned.
  

Request: Fetching an account specifying audit=MINIMAL

curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Content-Type: application/json" \
-H "X-Killbill-CreatedBy: demo" \
"http://127.0.0.1:8080/1.0/kb/accounts/e8877928-0226-488d-9272-07a5e66d897f?audit=MINIMAL" 

Account result = accountApi.getAccount(accountId,
                                      false,
                                      false,
                                      AuditLevel.MINIMAL,
                                      requestOptions);

TODO  Api does not exist ;-(

Response:

{
  ...
  "auditLogs": [
    {
      "changeType": "INSERT",
      "changeDate": "2018-02-05T22:39:53.000Z",
      "changedBy": "demo",
      "reasonCode": null,
      "comments": null,
      "userToken": "4858a67e-03b0-4d94-8a8c-bcd6e8599452"
    }
  ]
}  

Every API that retrieves information, whether associated with a specific resource, or with a list of resources, may return audit logs.

Audit and history information associated with a given resource is always stored atomically to ensure that if the state is changed, such audit and history information exists and is accurate.

Versioning

Kill Bill Server

Kill Bill software is composed of many different repositories, all of them hosted on our github account.

The Kill Bill server version, or simply Kill Bill version, is the one from the killbill repository, and more specifically since we are using maven to build, this is indicated in the corresponding pom.xml. This repository depends on a few others, each having their own versions:

• killbill-api: APIs used by plugins to communicate with Kill Bill core
• killbill-plugin-api: APIs used by Kill Bill core to communicate with plugins
• killbill-commons: Common code across modules
• killbill-platform: Platform related code such as OSGI framework, webapp pieces
• killbill-client: Java client, only used for integration tests inside killbill repository.

The version for all these dependencies is managed in the parent pom.xml. So in particular, for a given Kill Bill version, you can look up the version of the parent pom.xml and from there access all the dependencies.

The current stable and production ready version of Kill Bill is 0.22.y. You should use the latest relased (y) version as it may contain critical bug fixes.

• Any bug fixes will result in a new version identified by incrementing the patch number (y). We guarantee compatibility of these versions with those immediately preceding them. Each version will be accompanied by release notes on github - e.g 0.22.8 release notes.
• New development may happen in parallel. This may lead to the release of development versions. Such versions are not yet deemed stable, and will not be supportetd on the public mailing list.

The choice of releasing 0.x.y and not 1.x.y is motivated by our desire to add additional features in upcoming releases, and is in no way a statement about code instability.

More information on Kill Bill versions can be found here.

Client Libraries

Our client libraries contain a README section to describe their compatibility with the Kill Bill server. For instance, such compatibility mapping can be seen in our java client here.

Plugins

Each plugin also has its own version, and we also keep a README with the mapping section. For example, such a section for the adyen payment plugin can be found here.

We also keep a global repository for all plugins here. The simple file-based approach is an internal implementation. This brings us to our next topic, KPM.

KPM

KPM, The Kill Bill Package Manager, provides among other things the ability to retrieve version mapping for dependencies and plugins -- see the example on the right side.

# Look up version dependencies matching Kill Bill release 0.22.8:
> kpm info  --version=0.22.8

Fetching info for version 0.22.8...
Dependencies for version 0.22.8
  killbill 0.22.8
  killbill-oss-parent 0.143.60
  killbill-api 0.53.17
  killbill-plugin-api 0.26.4
  killbill-commons 0.23.11
  killbill-platform 0.39.15

Known plugins for KB version 0.22.8
  analytics 7.0.8
  avatax 0.7.0
  email-notifications 0.6.1
  payment-test 7.0.4
  stripe 7.0.4
  ...

Errors

Kill Bill relies on HTTP response codes to indicate the success or failure of an API request:

• 2xx status indicates success
• 4xx status often indicates a client side error -- e.g missing madatory API field
• 5xx status indicates an error with Kill Bill's servers or third party system -- e.g payment gateway returns 5xx.

HTTP status code summary:
200 - OK: A response body may be returned.
201 - Created: Success in creating a new resource. A Location header is returned to indicate the uri that can be used to fetch the resource
202 - Accepted: The request has been accepted and will be processed asynchronously.
204 - No Content: The request was processed sucesfully but no response body is returned.
400 - Bad Request: Invalid/missing parameter from client.
401 - Unauthorized: Authorization failed.
402 - Request Failed: Request parameter were valid but request failed -- insufficient fund on a payment request.
404 - Not Found: The requested resource does not exist.
409 - Conflict: The request conflicts with another request.
422 - Unprocessable Entity: Payment control plugin aborted the call.
500 - Unexpected system error.
502 - Bad Gateway : Unknow failure from payment plugin (PLUGIN_FAILURE).
503 - Service Unavailable: Kill Bill or a third party system -- e.g payment gateway -- is unavailable.
504 - Gateway Timeout: Payment gateway timed out.

In addition to these error codes, the system will often return some json to provide more details about the error:

• code : Each error in Kill Bill is associated with a an ErrorCode.
• formattedMsg : A description of the error for the specific resource(s).
• cause : An optional stack trace.

Additional Resources

Our main documentation is found here.

Tenant

Tenant Resource

Kill Bill has been designed from the ground up as a multi-tenant system, that is, one where multiple unrelated deployments can be hosted on the same physical system. Each deployment has its own separate configuration, catalog, and plugins, and of course its data set is kept entirely separate from the others. RBAC control allows different users/admin/apps to access zero, one or multiple tenants. This blog illustrates some interesting use cases. The Tenant resource allows the management of such tenants.

The attributes of the Tenant resource object are the following:

Name	Type	Generated by	Description
tenantId	string	system	UUID for this tenant
externalKey	string	system or user	Optional external key provided by the client
apiKey	string	user	The API key associated with the tenant
apiSecret	string	user	The API secret associated with the tenant. This value is hashed and cannot be retrieved.
auditLogs	array	system	Array of audit log records for this tenant

Note that The tenant itself has very few attributes, as most attributes belong to the individual accounts and related resources.

Tenant

These endpoints manage information that is maintained at the tenant level. Unless otherwise stated, the tenant is identified by its API key in the header.

Create a tenant

This API creates a new tenant. NOTE: If you create a tenant using this API, it will not be recognized immediately by KAUI because KAUI will be unable to retrieve the apiSecret. To fix this, you should "create" the same tenant separately after logging into KAUI. This will not create another tenant, but it will synchronize KAUI with the one already created.

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -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 '{ "apiKey": "bob", "apiSecret": "lazar"}' \
    "http://127.0.0.1:8080/1.0/kb/tenants"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

UUID tenantId = null;
String externalKey = null;
String apiKey = "bob";
String apiSecret = "lazar";
ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

Tenant body = new Tenant(tenantId,
                         externalKey,
                         apiKey,
                         apiSecret,
                         EMPTY_AUDIT_LOGS);

tenantApi.createTenant(body, requestOptions);

tenant = KillBillClient::Model::Tenant.new
tenant.external_key = "demo_external_key"
tenant.api_key = "demo_api_key"
tenant.api_secret = "demo_api_secret"

use_global_defalut = true
user = "demo"
reason = nil
comment = nil

tenant.create(use_global_defalut, 
              user, 
              reason, 
              comment, 
              options)

tenantApi = killbill.api.TenantApi()

body = Tenant(api_key='demo_api_key', api_secret='demo_api_secret')

tenantApi.create_tenant(body, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/e7b03c81-f41a-4eb7-a645-b9166057f186
< Content-Type: application/json
< Content-Length: 0

class Tenant {
    tenantId: 5cce926f-7f3a-4007-a5a0-e5b55fc50079
    externalKey: null
    apiKey: bob
    apiSecret: lazar
    auditLogs: []
}

{
   "tenantId":"ab5981c2-de14-43d6-a35b-a2ed0b28c746",
   "externalKey":"demo_external_key",
   "apiKey":"bob
}

no content

Request Body

A JSON string representing a Tenant resource. The only parameters required are apiKey and apiSecret. The externalKey is optional and will be set to null if not supplied. The tenantId is generated by the system.

Query Parameters

Name	Type	Required	Default	Description
useGlobalDefault	boolean	false	false	If true, configure the tenant with a default catalog

Setting the useGlobalDefault parameter to true can be used for test purposes. This will configure the tenant with a default catalog, and therefore make it easy to quickly start playing with the apis. Note that in order to then upload a new custom catalog, one would need to invalidate the caches for this tenant.

Response

If successful, returns a status code of 201 and an empty body. In addition a Location parameter is returned in the header. This parameter gives the URL for the tenant, including the tenantId.

Retrieve a tenant by id

Retrieves a tenant resource, given its ID.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/{tenantId}

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/tenants/6907712e-e940-4033-8695-36894db128d3"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

UUID tenantId = UUID.fromString("6907712e-e940-4033-8695-36894db128d3");
tenantApi.getTenant(tenantId, requestOptions);

tenant_id = "ab5981c2-de14-43d6-a35b-a2ed0b28c746"

KillBillClient::Model::Tenant.find_by_id(tenant_id, options)

tenantApi = killbill.api.TenantApi()

tenant.get_tenant(tenant_id='3d90ec45-c640-4fd7-abde-798bc582513b')

Example Response:

{
  "tenantId": "6907712e-e940-4033-8695-36894db128d3",
  "externalKey": "1532546166-326384",
  "apiKey": "bob",
  "apiSecret": null,
  "auditLogs": []
}

class Tenant {
  "tenantId": "6907712e-e940-4033-8695-36894db128d3",
  "externalKey": "1532546166-326384",
  "apiKey": "bob",
  "apiSecret": null,
  "auditLogs": []
}

{
   "tenantId":"ab5981c2-de14-43d6-a35b-a2ed0b28c746",
   "externalKey":"demo_external_key",
   "apiKey":"bob"
}

{'api_key': 'udwg',
 'api_secret': None,
 'audit_logs': [],
 'external_key': None,
 'tenant_id': '3d90ec45-c640-4fd7-abde-798bc582513b'}

Query Parameters

none

Response

If successful, returns a status code of 200 and a tenant resource object. The apiSecret attribute is returned as null, since it cannot be retrieved.

Retrieve a tenant by its API key

Retrieves a tenant resource, given its apiKey. The apiKey is passed as a query parameter.

HTTP Request

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

Example Request:

curl -v \
    -u admin:password \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/tenants?apiKey=bob"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String apiKey = "bob";

tenantApi.getTenantByApiKey(apiKey, requestOptions);

api_key = "demo_api_key"

KillBillClient::Model::Tenant.find_by_api_key(api_key, options)

tenantApi = killbill.api.TenantApi()

tenantApi.get_tenant_by_api_key(api_key='bob')

Example Response:

{
  "tenantId": "6907712e-e940-4033-8695-36894db128d3",
  "externalKey": "1532546166-326384",
  "apiKey": "bob",
  "apiSecret": null,
  "auditLogs": []
}

{
  "tenantId": "6907712e-e940-4033-8695-36894db128d3",
  "externalKey": "1532546166-326384",
  "apiKey": "bob",
  "apiSecret": null,
  "auditLogs": []
}

{
   "tenantId":"ab5981c2-de14-43d6-a35b-a2ed0b28c746",
   "externalKey":"demo_external_key",
   "apiKey":"bob"
}

{'api_key': 'bob',
 'api_secret': None,
 'audit_logs': [],
 'external_key': None,
 'tenant_id': '3d90ec45-c640-4fd7-abde-798bc582513b'}

Query Parameters

Name	Type	Required	Default	Description
apiKey	string	true	none	api key

Response

If successful, returns a status code of 200 and a tenant resource object. The apiSecret attribute is returned as null, since it cannot be retrieved.

Push Notifications

Push notifications are a convenient way to get notified about events from the system. One can register a callback, i.e, a valid URL that will be called whenever there is an event dispatched for this tenant. Note that this can result in a large number of calls; every time there is a state change for one of the Accounts in this tenant, the callback will be invoked.

In case of error, the system will retry the callback as defined by the system property org.killbill.billing.server.notifications.retries.

See push notification documentation here for further information.

Register a push notification

Register a callback URL for this tenant for push notifications.The key name is PUSH_NOTIFICATION_CB. The API sets the value of this key, replacing any previous value.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/tenants/registerNotificationCallback

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/tenants/registerNotificationCallback?cb=http://demo/callmeback'

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String cb = "http://demo/callmeback";

TenantKeyValue result = tenantApi.registerPushNotificationCallback(cb, requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

tenantApi.register_push_notification_callback(created_by='demo', cb='http://demo/callmeback')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/registerNotificationCallback
< Content-Type: application/json
< Content-Length: 0

class TenantKeyValue {
    key: PUSH_NOTIFICATION_CB
    values: [http://demo/callmeback]
}

TODO

no content

Query Parameters

Name	Type	Required	Default	Description
cb	string	true	none	callback URL to register

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location item is returned in the header giving the URL for this callback.

Retrieve a registered push notification

Gets the push notification registered for this tenant, if any.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/registerNotificationCallback

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/tenants/registerNotificationCallback"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

TenantKeyValue result = tenantApi.getPushNotificationCallbacks(requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

tenantApi.get_push_notification_callbacks()

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "PUSH_NOTIFICATION_CB",
  "values": [
    "http://demo/callmeback"
  ]
}

class TenantKeyValue {
    key: PUSH_NOTIFICATION_CB
    values: [http://demo/callmeback]
}

TODO

{'key': 'PUSH_NOTIFICATION_CB', 'values': ['http://demo/callmeback']}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a body containing a key-value object as follows:

{ "key": "PUSH_NOTIFICATION_CB", "values": list containing the callback URL, if any }

Delete a registered push notification

Deletes the registered callback URL, if any.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tenants/registerNotificationCallback

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/tenants/registerNotificationCallback"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

tenantApi.deletePushNotificationCallbacks(requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

tenantApi.delete_push_notification_callbacks(created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Tenant Key-Value Pairs

These endpoints provide a mechanism to register and manage {key, value} pairs for a given tenant. This functionality is used internally by the system to keep track of all the per-tenant configuration, including system properties, plugin configuration, and others discussed below. In addition, you can add user keys to keep track of additional information that may be desired. For example, some global setting that would be accessible for all plugins could be stored here.

Add a per tenant user key/value

This API adds a key-value pair to the tenant database. If the key already exists its value is replaced. The key is given as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/{keyName}

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d "demo_value" \
    "http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/demo_key"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String keyName = "demo_value";
String body = "demo_value";
TenantKeyValue result = tenantApi.insertUserKeyValue(keyName, body, requestOptions);

user = "demo"
reason = nil
comment = nil

key_name = "demo_value"
key_value = "demo_value"

KillBillClient::Model::Tenant.upload_tenant_user_key_value(key_name, 
                                                           key_value, 
                                                           user, 
                                                           reason, 
                                                           comment, 
                                                           options)

tenantApi = killbill.api.TenantApi()

key_name = 'demo_value'
body = 'demo_value'

tenantApi.insert_user_key_value(key_name, body, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/userKeyValue/demo_key
< Content-Type: application/json
< Content-Length: 0

class TenantKeyValue {
    key: demo_key
    values: [demo_value]
}

{
   "key":"demo_key",
   "values":[
      "demo_value"
   ]
}

no content

Request Body

The body contains a single string representing the value.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location item is returned in the header giving the URL for this key-value pair.

Retrieve a per tenant user key value

Retrieves the value for a specified key, if it exists, from the tenant database. The key name is given as a path parameter.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/{keyName}

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/tenants/userKeyValue/demo_value"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String keyName = "demo_value";

TenantKeyValue result = tenantApi.getUserKeyValue(keyName, requestOptions);

key_name = "demo_value"

KillBillClient::Model::Tenant.get_tenant_user_key_value(key_name, options)

tenantApi = killbill.api.TenantApi()

key_name = 'demo_value'

tenantApi.get_user_key_value(key_name)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "demo_value",
  "values": [
    "demo_value",
    "demo_value"
  ]
}

class TenantKeyValue {
    key: demo_value
    values: [demo_value]
}

{
   "key":"demo_value",
   "values":[
      "demo_value"
   ]
}

{'key': 'demo_value', 'values': []}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a tenant key value object. The key value object includes the key name and a JSON array containing the value, if any, or a comma-separated list of values. For example:

{ "key": "MYKEY", "values": [ "value1", "value2" ] }

If the key does not exist no error is signalled but the values list is empty.

Delete a per tenant user key/value

Deletes a key and its value, if it exists, from the tenant database. The key is given as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/{keyName}

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/tenants/userKeyValue/demo_value"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String keyName = "demo_value";

tenantApi.deleteUserKeyValue(keyName, requestOptions);

user = "demo"
reason = nil
comment = nil
key_value = "demo_value"

KillBillClient::Model::Tenant.delete_tenant_user_key_value(key_value, 
                                                           user,
                                                           reason, 
                                                           comment, 
                                                           options)

tenantApi = killbill.api.TenantApi()

key_name = 'demo_value'

tenantApi.delete_user_key_value(key_name, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. No error is signalled if the key does not exist.

Retrieve per tenant keys and values based on a key prefix

This API enables searching for existing keys based on a prefix of the key name. For example, a search string of "MYK" would match keys such as MYKEY1, MYKEY2, etc. The search string is given as a path parameter.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig/{keyPrefix}/search

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/tenants/uploadPerTenantConfig/PER_TENANT/search"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String keyPrefix = "PER_TENANT";

TenantKeyValue result = tenantApi.getAllPluginConfiguration(keyPrefix, requestOptions);

key_prefix = "PER_TENANT"

KillBillClient::Model::Tenant.search_tenant_config(key_prefix, options)

tenantApi = killbill.api.TenantApi()

tenantApi.get_all_plugin_configuration(key_prefix='tenant_config')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "PER_TENANT_CONFIG",
  "values": [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]
}

class TenantKeyValue {
    key: PER_TENANT_CONFIG
    values: [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]
}

TODO

{'key': 'PER_TENANT_CONFIG', 'values': [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a tenant key value object containing the key and values for any keys that match the search string.

System Properties Configuration

These endpoints allow setting of some system properties on a per-tenant basis. Please refer to our configuartion guide to see what can be configured in the system. Some of the configuration can be overriden at the tenant level to allow for different behaviors.

Note that this is actually a special case of per-tenant key-value pairs; the key is "PER_TENANT_CONFIG" and the value is a comma-separated list of system properties with their values.

Add a per tenant system properties configuration

This API is used to set the value of specific system properties, overriding the system-wide values.

For example, in order to disable the invoice safety bound mechanism on a per-tenant level, this API could be used to set the per-tenant system property org.killbill.invoice.sanitySafetyBoundEnabled to false.

The API sets the value of the "PER_TENANT_CONFIG" key, replacing any previous value.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d "{"org.killbill.invoice.sanitySafetyBoundEnabled":"false"}" \
    "http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String body = "{\"org.killbill.invoice.sanitySafetyBoundEnabled\":\"false\"}";

TenantKeyValue result = tenantApi.uploadPerTenantConfiguration(body, requestOptions);

TODO

tenantApi = killbill.api.TenantApi()
body = '{"org.killbill.invoice.sanitySafetyBoundEnabled":"false"}'

tenantApi.upload_per_tenant_configuration(body, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/uploadPerTenantConfig
< Content-Type: application/json
< Content-Length: 0

class TenantKeyValue {
    key: PER_TENANT_CONFIG
    values: [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]
}

TODO

no content

Request Body

A JSON string representing the per-tenant system property and its value.

Query Parameters

None.

Response

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

Retrieve a per tenant system properties configuration

Retrieves the per-tenant system property settings, which are given as the value of the key PER_TENANT_CONFIG.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig

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/tenants/uploadPerTenantConfig"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

TenantKeyValue result = tenantApi.getPerTenantConfiguration(requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

tenantApi.get_per_tenant_configuration()

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "PER_TENANT_CONFIG",
  "values": [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]
}

class TenantKeyValue {
    key: PER_TENANT_CONFIG
    values: [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]
}

TODO

{'key': 'PER_TENANT_CONFIG', 'values': [
    "{org.killbill.invoice.sanitySafetyBoundEnabled:false}"
  ]}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a tenant key value object for the key PER_TENANT_CONFIG.

Delete a per tenant system properties configuration

Deletes any current per tenant system properties configuration parameters, which are given as the values of the PER_TENANT_CONFIG key.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tenants/uploadPerTenantConfig

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/tenants/uploadPerTenantConfig"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

tenantApi.deletePerTenantConfiguration(requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

tenantApi.delete_per_tenant_configuration(created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Plugin Configuration

Plugins also support configuration on a per-tenant level. Please refer to our plugin configuration manual for more details.

An example of the use of such per-tenant properties is to configure a payment plugin with different API keys, one set of keys for each tenant. This allows for a true multi-tenant deployment where plugins have different configuration based on the tenant in which they operate.

Upon adding or deleting a new per-tenant plugin configuration, the system will generate a TENANT_CONFIG_CHANGE/TENANT_CONFIG_DELETION event, which can be handled in the plugin to refresh its configuration. In multi-node scenarios, events will be dispatched on each node, that is, on each plugin instance so they end up with a consistent view. A lot of the logic to handle configuration update has been implemented in our plugin frameworks (see ruby framework and java framework).

As with the system properties configuration, this is actually a special case of per-tenant key-value pairs. The following endpoints provide the ability to configure plugins on a per-tenant level.

Add a per tenant configuration for a plugin

Adds a per tenant key-value pair for the specified plugin. The plugin name is given as a path parameter. The key name is PLUGIN_CONFIG_*plugin* where plugin is the plugin name. The API sets the value of this key, replacing any previous value.

The value string uploaded is plugin dependent but typically consists of key/value properties, or well formatted yml or a properties file.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/{pluginName}

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d @./config.properties \
    "http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String pluginName = "PLUGIN_FOO";
String pluginConfig = "plugin configuration string";

TenantKeyValue result = tenantApi.uploadPluginConfiguration(pluginName, pluginConfig, requestOptions);

plugin_name = "demo_plugin"
plugin_config = "tenant_config"
user = "demo"
reason = nil
comment = nil

KillBillClient::Model::Tenant.upload_tenant_plugin_config(plugin_name, 
                                                          plugin_config, 
                                                          user, 
                                                          reason, 
                                                          comment, 
                                                          options)

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'
body = 'tenant_config'

tenantApi.upload_plugin_configuration(plugin_name, body, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/uploadPluginConfig/demo_plugin
< Content-Type: application/json
< Content-Length: 0

class TenantKeyValue {
    key: PLUGIN_CONFIG_PLUGIN_FOO
    values: 

    :my_plugin:
      :test: True
      :log_file: /var/tmp/myplugin.log
      :username: xx
      :password: yoyoyo
      :merchant_id:
        :USD: '0689870'

    :database:
      :adapter: sqlite3
      :database: test.db

    ]
}

{
   "key":"PLUGIN_CONFIG_demo_plugin",
   "values":[
      "tenant_config"
   ]
}

no content

Request Body

The request body can be specified as a JSON string consisting of the key-value pairs for the plugin configuration. Alternatively, the plugin configuration can be specified in a yml or properties file and its path can be specified.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. A Location header is also returned giving the URL of the key-value pair.

Retrieve a per tenant configuration for a plugin

Gets the per tenant configuration value string for a specified plugin. The plugin name is given as a path parameter.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/{pluginName}

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/tenants/uploadPluginConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

final String pluginName = "PLUGIN_FOO";

final TenantKeyValue result = tenantApi.getPluginConfiguration(pluginName, requestOptions);

plugin_name = "demo_plugin"

KillBillClient::Model::Tenant.get_tenant_plugin_config(plugin_name, options)

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'

tenantApi.get_plugin_configuration(plugin_name)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "PLUGIN_CONFIG_demo_plugin",
  "values": [
    "tenant_config"
  ]
}

class TenantKeyValue {
    key: PLUGIN_CONFIG_PLUGIN_FOO
    values: 

    :my_plugin:
      :test: True
      :log_file: /var/tmp/myplugin.log
      :username: xx
      :password: yoyoyo
      :merchant_id:
        :USD: '0689870'

    :database:
      :adapter: sqlite3
      :database: test.db

    ]
}

{
   "key":"PLUGIN_CONFIG_demo_plugin",
   "values":[
      "tenant_config"
   ]
}

{'key': 'PLUGIN_CONFIG_demo_plugin', 'values': []}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a tenant key value object for the key PLUGIN_CONFIG_*plugin*.

Delete a per tenant configuration for a plugin

Deletes the per tenant plugin configuration value for the appropriate key. The plugin name is given as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginConfig/{pluginName}

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/tenants/uploadPluginConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

final String pluginName = "PLUGIN_FOO";

tenantApi.deletePluginConfiguration(pluginName, requestOptions);

user = "demo"
reason = nil
comment = nil

plugin_name = "demo_plugin"

KillBillClient::Model::Tenant.delete_tenant_plugin_config(plugin_name, 
                                                          user, 
                                                          reason, 
                                                          comment, 
                                                          options)

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'

tenantApi.delete_plugin_configuration(plugin_name, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Returns

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

Payment State Machines

This is a somewhat advanced use case to override the default internal payment state machine within Kill Bill. Please refer to our payment manual for more details about payment states.

The endpoints below allow you to override such state machines on a per-tenant level.

Add a per tenant payment state machine for a plugin

Adds a per tenant key-value pair for the specified plugin. The plugin name is given as a path parameter. The key name is PLUGIN_PAYMENT_STATE_MACHINE_*plugin* where plugin is the plugin name. The API sets the value of this key, replacing any previous value.

The state machine is defined in an XML file. The complete XML file becomes the value of the key.

HTTP Request

Let's say we want to overwrite the default Kill Bill payment state machine for the payment plugin demo_plugin, and assuming SimplePaymentStates.xmlis a valid payment state machine XML file, then the HTTP Request would be:

POST http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/{pluginName}

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '@SimplePaymentStates.xml' \
    "http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String pluginName = "noop";
String stateMachineConfig = getResourceBodyString("SimplePaymentStates.xml");

TenantKeyValue result = tenantApi.uploadPluginPaymentStateMachineConfig(pluginName, 
                                                                        stateMachineConfig, 
                                                                        requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'
body = 'SimplePaymentStates.xml'

tenantApi.upload_plugin_payment_state_machine_config(plugin_name, body, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/demo_plugin
< Content-Type: application/json
< Content-Length: 0

class TenantKeyValue {
    key: PLUGIN_PAYMENT_STATE_MACHINE_noop
    values: [<?xml version="1.0" encoding="UTF-8"?>


    <stateMachineConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:noNamespaceSchemaLocation="StateMachineConfig.xsd">

        <stateMachines>
            <stateMachine name="BIG_BANG">
                <states>
                    <state name="BIG_BANG_INIT"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>BIG_BANG_INIT</initialState>
                        <operation>OP_DUMMY</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>BIG_BANG_INIT</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_DUMMY"/>
                </operations>
            </stateMachine>
            <stateMachine name="AUTHORIZE">
                <states>
                    <state name="AUTH_INIT"/>
                    <state name="AUTH_SUCCESS"/>
                    <state name="AUTH_FAILED"/>
                    <state name="AUTH_ERRORED"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>AUTH_SUCCESS</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>FAILURE</operationResult>
                        <finalState>AUTH_FAILED</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>EXCEPTION</operationResult>
                        <finalState>AUTH_ERRORED</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_AUTHORIZE"/>
                </operations>
            </stateMachine>
        </stateMachines>

        <linkStateMachines>
            <linkStateMachine>
                <initialStateMachine>BIG_BANG</initialStateMachine>
                <initialState>BIG_BANG_INIT</initialState>
                <finalStateMachine>AUTHORIZE</finalStateMachine>
                <finalState>AUTH_INIT</finalState>
            </linkStateMachine>
        </linkStateMachines>
    </stateMachineConfig>
    ]
}

TODO

no content

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location item is returned in the header giving the URL for the payment state machine.

Retrieve a per tenant payment state machine for a plugin

Retrieves the value for the appropriate payment state machine key for the specified plugin. If present, this value should be the complete XML file that defines the state machine.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/{pluginName}

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/tenants/uploadPluginPaymentStateMachineConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String pluginName = "noop";

TenantKeyValue result = tenantApi.getPluginPaymentStateMachineConfig(pluginName, requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'

tenantApi.get_plugin_payment_state_machine_config(plugin_name)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "key": "PLUGIN_PAYMENT_STATE_MACHINE_demo_plugin",
  "values": [<?xml version="1.0" encoding="UTF-8"?>

    <stateMachineConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:noNamespaceSchemaLocation="StateMachineConfig.xsd">

        <stateMachines>
            <stateMachine name="BIG_BANG">
                <states>
                    <state name="BIG_BANG_INIT"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>BIG_BANG_INIT</initialState>
                        <operation>OP_DUMMY</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>BIG_BANG_INIT</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_DUMMY"/>
                </operations>
            </stateMachine>
            <stateMachine name="AUTHORIZE">
                <states>
                    <state name="AUTH_INIT"/>
                    <state name="AUTH_SUCCESS"/>
                    <state name="AUTH_FAILED"/>
                    <state name="AUTH_ERRORED"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>AUTH_SUCCESS</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>FAILURE</operationResult>
                        <finalState>AUTH_FAILED</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>EXCEPTION</operationResult>
                        <finalState>AUTH_ERRORED</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_AUTHORIZE"/>
                </operations>
            </stateMachine>
        </stateMachines>

        <linkStateMachines>
            <linkStateMachine>
                <initialStateMachine>BIG_BANG</initialStateMachine>
                <initialState>BIG_BANG_INIT</initialState>
                <finalStateMachine>AUTHORIZE</finalStateMachine>
                <finalState>AUTH_INIT</finalState>
            </linkStateMachine>
        </linkStateMachines>
    </stateMachineConfig>
    ]
}

class TenantKeyValue {
    key: PLUGIN_PAYMENT_STATE_MACHINE_noop
    values: [<?xml version="1.0" encoding="UTF-8"?>

    <stateMachineConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:noNamespaceSchemaLocation="StateMachineConfig.xsd">

        <stateMachines>
            <stateMachine name="BIG_BANG">
                <states>
                    <state name="BIG_BANG_INIT"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>BIG_BANG_INIT</initialState>
                        <operation>OP_DUMMY</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>BIG_BANG_INIT</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_DUMMY"/>
                </operations>
            </stateMachine>
            <stateMachine name="AUTHORIZE">
                <states>
                    <state name="AUTH_INIT"/>
                    <state name="AUTH_SUCCESS"/>
                    <state name="AUTH_FAILED"/>
                    <state name="AUTH_ERRORED"/>
                </states>
                <transitions>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>SUCCESS</operationResult>
                        <finalState>AUTH_SUCCESS</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>FAILURE</operationResult>
                        <finalState>AUTH_FAILED</finalState>
                    </transition>
                    <transition>
                        <initialState>AUTH_INIT</initialState>
                        <operation>OP_AUTHORIZE</operation>
                        <operationResult>EXCEPTION</operationResult>
                        <finalState>AUTH_ERRORED</finalState>
                    </transition>
                </transitions>
                <operations>
                    <operation name="OP_AUTHORIZE"/>
                </operations>
            </stateMachine>
        </stateMachines>

        <linkStateMachines>
            <linkStateMachine>
                <initialStateMachine>BIG_BANG</initialStateMachine>
                <initialState>BIG_BANG_INIT</initialState>
                <finalStateMachine>AUTHORIZE</finalStateMachine>
                <finalState>AUTH_INIT</finalState>
            </linkStateMachine>
        </linkStateMachines>
    </stateMachineConfig>
    ]
}

TODO

{'key': 'PLUGIN_PAYMENT_STATE_MACHINE_demo_plugin', 'values': []}

Query Parameters

None.

Response

If successful, returns a status code of 200 and a key value object for the key PLUGIN_PAYMENT_STATE_MACHINE_*plugin*. The value of this key should be the complete XML file that defines the payment state machine.

Delete a per tenant payment state machine for a plugin

Deletes the payment state machine for the specified plugin for this tenant. The plugin reverts to the default payment state machine.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/{pluginName}

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://localhost:8080/1.0/kb/tenants/uploadPluginPaymentStateMachineConfig/demo_plugin"

import org.killbill.billing.client.api.gen.TenantApi;
protected TenantApi tenantApi;

String pluginName = "noop";

tenantApi.deletePluginPaymentStateMachineConfig(pluginName, requestOptions);

TODO

tenantApi = killbill.api.TenantApi()

plugin_name = 'demo_plugin'

tenantApi.delete_plugin_payment_state_machine_config(plugin_name, created_by='demo')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Returns

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

Catalog

The Catalog is at the heart of the Kill Bill subscription and billing systems. It provides complete current information on products available, subscription plans, billing options, and much more. Each tenant has a single catalog, but different tenants may have completely different catalogs.

The catalog for a given tenant may be updated to new versions from time to time. This provides the ability to deprecate old products, add new ones, or change prices for existing products. Older versions remain available in case they are needed. If a new version is uploaded, new subscriptions will use the new version, but existing subscriptions may either depend on their original versions (grandfathering use case) or use the latest version (price update use case). Please refer to the catalog section of our subscription billing documentation for additional details.

KAUI, our admin UI, provides the ability to upload a simple plan. The simple plan provides a way to ease testing and to play with the system. See API section Simple Plan.

A tenant has several options for setting up their catalog. You can choose the option that best meets your needs:

1. Use the default test catalog that ships with Kill Bill by creating a tenant with useGlobalDefault=true
2. Use the Simple Plan API from KAUI to get started quickly (no need to create an XML catalog, simply use the UI and add the plans you need).
3. Write your own complete catalog as an XML file and upload it. Some examples of catalog can be found in our test repo. For validation, check our manual or use our cloud validation tool after creating an account.
4. Write a custom Catalog plugin. This is only for advanced users with special needs.

For a full discussion of the KillBill catalog, see the Catalog section in the Subscription Guide.

The Catalog API offers basic CRUD operations, allowing you to upload, retrieve and delete catalog versions.

Catalog Resource

At a very high level, the Catalog consists of the following main components:

• Products : List of products available - e.g Gold product.
• Plans : List of subscription plans available for each product - e.g gold-monthly, monthly subscription for the Gold product.
• Rules : Business rules for subscriptions - e.g. when certain changes should take effect.
• Price Lists : Lists of applicable Plans.

Full details about the elements of a Catalog are given in the links cited above. The Catalog is maintained as an XML file.

Catalog

Upload a catalog as XML

This endpoint uploads a complete catalog in XML format. This becomes the current version of the Catalog for this Tenant.

Note that the naming for the various entities is based on what the XML spec specifies, and in particular the name elements need to be globally unique in the catalog and must conform to the XML NCName definition. This means that they cannot contain symbol characters like :, @, $, %, &, /, +, ,, ;,, whitespace characters or parentheses, and they cannot begin with a number, dot or minus character.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/catalog/xml

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/xml" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><catalog> ...' \
    "http://127.0.0.1:8080/1.0/kb/catalog/xml"

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

String body = getResourceBodyString(catalog);

catalogApi.uploadCatalogXml(body, requestOptions);

catalog_file_xml = resource_file.read
KillBillClient::Model::Catalog.upload_tenant_catalog(catalog_file_xml, 
                                                     user,
                                                     reason,
                                                     comment,
                                                     options)

catalogApi = killbill.api.CatalogApi()
xml_catalog = open("../resources/SpyCarBasic.xml", "r+").read()

catalogApi.upload_catalog_xml(xml_catalog, 
                              created_by, 
                              api_key, 
                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/catalog/xml
< Content-Type: text/xml
< Content-Length: 0

no content

no content

no content

Request Body

Contains the complete catalog in XML format

Query Parameters

None.

Response

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

Retrieve the catalog as XML

This endpoint retrieves the Catalog for a specified date in XML format. If there are multiple versions, the latest version with an effective date not later than the requested date is returned. If the effective date for all versions is greater than the requested date, the earliest version is returned.

For example, suppose there are two versions of the catalog, the current version dated 2020-01-01 (Jan. 1, 2020) and a previous version dated 2019-01-01. Then

• A request with no effective date would retrieve the current version
• A request with an effective date of 2020-01-01 or later would retrieve the current version
• A request with an effective date of 2019-01-01 or later, but before 2020-01-01, would retrieve the previous version
• A request with an effective date earlier than 2019-01-01 would retrieve the previous version, as it is the earliest version available.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/xml

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/xml" \
    "http://localhost:8080/1.0/kb/catalog/xml"  

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

LocalDate requestedDate = null;
UUID accountId = null;

String catalog = catalogApi.getCatalogXml(requestedDate, 
                                          accountId, 
                                          requestOptions);

requested_date = nil

KillBillClient::Model::Catalog.get_tenant_catalog_xml(requested_date,
                                                      options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_catalog_xml(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <catalogs>
    <versions>
      <version>
        <effectiveDate>2013-02-08T00:00:00Z</effectiveDate>
        <catalogName>SpyCarBasic</catalogName>
        <currencies>
          <currency>USD</currency>
          <currency>GBP</currency>
        </currencies>
        <units/>
        <products>
          <product name="Basic" prettyName="Basic">
            <category>BASE</category>
            <included/>
            <available/>
            <limits/>
          </product>
          <product name="Sports" prettyName="Sports">
            <category>BASE</category>
            <included/>
            <available/>
            <limits/>
          </product>
          <product name="Standard" prettyName="Standard">
            <category>BASE</category>
            <included/>
            <available/>
            <limits/>
          </product>
          <product name="Super" prettyName="Super">
            <category>ADD_ON</category>
            <included/>
            <available/>
            <limits/>
          </product>
        </products>
        <rules>
          <changePolicy>
            <changePolicyCase>
              <policy>IMMEDIATE</policy>
            </changePolicyCase>
          </changePolicy>
          <changeAlignment>
            <changeAlignmentCase>
              <alignment>START_OF_BUNDLE</alignment>
            </changeAlignmentCase>
          </changeAlignment>
          <cancelPolicy>
            <cancelPolicyCase>
              <policy>IMMEDIATE</policy>
            </cancelPolicyCase>
          </cancelPolicy>
          <createAlignment>
            <createAlignmentCase>
              <alignment>START_OF_BUNDLE</alignment>
            </createAlignmentCase>
          </createAlignment>
          <billingAlignment>
            <billingAlignmentCase>
              <alignment>ACCOUNT</alignment>
            </billingAlignmentCase>
          </billingAlignment>
          <priceList>
            <priceListCase>
              <toPriceList>DEFAULT</toPriceList>
            </priceListCase>
          </priceList>
        </rules>
        <plans>
          <plan name="basic-annual" prettyName="basic-annual">
            <product>Basic</product>
            <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
            <initialPhases/>
            <finalPhase type="EVERGREEN">
              <duration>
                <unit>UNLIMITED</unit>
                <number>-1</number>
              </duration>
              <recurring>
                <billingPeriod>ANNUAL</billingPeriod>
                <recurringPrice>
                  <price>
                    <currency>USD</currency>
                    <value>1000</value>
                  </price>
                </recurringPrice>
              </recurring>
              <usages/>
            </finalPhase>
            <plansAllowedInBundle>-1</plansAllowedInBundle>
          </plan>
          <plan name="sports-monthly" prettyName="sports-monthly">
            <product>Sports</product>
            <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
            <initialPhases>
              <phase type="TRIAL">
                <duration>
                  <unit>DAYS</unit>
                  <number>30</number>
                </duration>
                <fixed type="ONE_TIME">
                  <fixedPrice/>
                </fixed>
                <usages/>
              </phase>
            </initialPhases>
            <finalPhase type="EVERGREEN">
              <duration>
                <unit>UNLIMITED</unit>
                <number>-1</number>
              </duration>
              <recurring>
                <billingPeriod>MONTHLY</billingPeriod>
                <recurringPrice>
                  <price>
                    <currency>GBP</currency>
                    <value>375.00</value>
                  </price>
                  <price>
                    <currency>USD</currency>
                    <value>500.00</value>
                  </price>
                </recurringPrice>
              </recurring>
              <usages/>
            </finalPhase>
            <plansAllowedInBundle>-1</plansAllowedInBundle>
          </plan>
          <plan name="standard-monthly" prettyName="standard-monthly">
            <product>Standard</product>
            <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
            <initialPhases>
              <phase type="TRIAL">
                <duration>
                  <unit>DAYS</unit>
                  <number>30</number>
                </duration>
                <fixed type="ONE_TIME">
                  <fixedPrice/>
                </fixed>
                <usages/>
              </phase>
            </initialPhases>
            <finalPhase type="EVERGREEN">
              <duration>
                <unit>UNLIMITED</unit>
                <number>-1</number>
              </duration>
              <recurring>
                <billingPeriod>MONTHLY</billingPeriod>
                <recurringPrice>
                  <price>
                    <currency>GBP</currency>
                    <value>75.00</value>
                  </price>
                  <price>
                    <currency>USD</currency>
                    <value>100.00</value>
                  </price>
                </recurringPrice>
              </recurring>
              <usages/>
            </finalPhase>
            <plansAllowedInBundle>-1</plansAllowedInBundle>
          </plan>
          <plan name="super-monthly" prettyName="super-monthly">
            <product>Super</product>
            <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
            <initialPhases>
              <phase type="TRIAL">
                <duration>
                  <unit>DAYS</unit>
                  <number>30</number>
                </duration>
                <fixed type="ONE_TIME">
                  <fixedPrice/>
                </fixed>
                <usages/>
              </phase>
            </initialPhases>
            <finalPhase type="EVERGREEN">
              <duration>
                <unit>UNLIMITED</unit>
                <number>-1</number>
              </duration>
              <recurring>
                <billingPeriod>MONTHLY</billingPeriod>
                <recurringPrice>
                  <price>
                    <currency>GBP</currency>
                    <value>750.00</value>
                  </price>
                  <price>
                    <currency>USD</currency>
                    <value>1000.00</value>
                  </price>
                </recurringPrice>
              </recurring>
              <usages/>
            </finalPhase>
            <plansAllowedInBundle>-1</plansAllowedInBundle>
          </plan>
        </plans>
        <priceLists>
          <defaultPriceList name="DEFAULT">
            <plans>
              <plan>basic-annual</plan>
              <plan>sports-monthly</plan>
              <plan>standard-monthly</plan>
              <plan>super-monthly</plan>
            </plans>
          </defaultPriceList>
        </priceLists>
      </version>
    </versions>
    <catalogName>SpyCarBasic</catalogName>
  </catalogs>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<catalogs>
    <versions>
        <version>
            <effectiveDate>2013-02-08T00:00:00Z</effectiveDate>
            <catalogName>SpyCarBasic</catalogName>
            <currencies>
                <currency>USD</currency>
                <currency>GBP</currency>
            </currencies>
            <units/>
            <products>
                <product name="Sports" prettyName="Sports">
                    <category>BASE</category>
                    <included/>
                    <available/>
                    <limits/>
                </product>
                <product name="Standard" prettyName="Standard">
                    <category>BASE</category>
                    <included/>
                    <available/>
                    <limits/>
                </product>
                <product name="Super" prettyName="Super">
                    <category>BASE</category>
                    <included/>
                    <available/>
                    <limits/>
                </product>
            </products>
            <rules>
                <changePolicy>
                    <changePolicyCase>
                        <policy>IMMEDIATE</policy>
                    </changePolicyCase>
                </changePolicy>
                <changeAlignment>
                    <changeAlignmentCase>
                        <alignment>START_OF_BUNDLE</alignment>
                    </changeAlignmentCase>
                </changeAlignment>
                <cancelPolicy>
                    <cancelPolicyCase>
                        <policy>IMMEDIATE</policy>
                    </cancelPolicyCase>
                </cancelPolicy>
                <createAlignment>
                    <createAlignmentCase>
                        <alignment>START_OF_BUNDLE</alignment>
                    </createAlignmentCase>
                </createAlignment>
                <billingAlignment>
                    <billingAlignmentCase>
                        <alignment>ACCOUNT</alignment>
                    </billingAlignmentCase>
                </billingAlignment>
                <priceList>
                    <priceListCase>
                        <toPriceList>DEFAULT</toPriceList>
                    </priceListCase>
                </priceList>
            </rules>
            <plans>
                <plan name="sports-monthly" prettyName="sports-monthly">
                    <product>Sports</product>
                    <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
                    <initialPhases>
                        <phase type="TRIAL">
                            <duration>
<unit>DAYS</unit>
<number>30</number>
                            </duration>
                            <fixed type="ONE_TIME">
<fixedPrice/>
                            </fixed>
                            <usages/>
                        </phase>
                    </initialPhases>
                    <finalPhase type="EVERGREEN">
                        <duration>
                            <unit>UNLIMITED</unit>
                            <number>-1</number>
                        </duration>
                        <recurring>
                            <billingPeriod>MONTHLY</billingPeriod>
                            <recurringPrice>
<price>
    <currency>GBP</currency>
    <value>375.00</value>
</price>
<price>
    <currency>USD</currency>
    <value>500.00</value>
</price>
                            </recurringPrice>
                        </recurring>
                        <usages/>
                    </finalPhase>
                    <plansAllowedInBundle>-1</plansAllowedInBundle>
                </plan>
                <plan name="standard-monthly" prettyName="standard-monthly">
                    <product>Standard</product>
                    <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
                    <initialPhases>
                        <phase type="TRIAL">
                            <duration>
<unit>DAYS</unit>
<number>30</number>
                            </duration>
                            <fixed type="ONE_TIME">
<fixedPrice/>
                            </fixed>
                            <usages/>
                        </phase>
                    </initialPhases>
                    <finalPhase type="EVERGREEN">
                        <duration>
                            <unit>UNLIMITED</unit>
                            <number>-1</number>
                        </duration>
                        <recurring>
                            <billingPeriod>MONTHLY</billingPeriod>
                            <recurringPrice>
<price>
    <currency>GBP</currency>
    <value>75.00</value>
</price>
<price>
    <currency>USD</currency>
    <value>100.00</value>
</price>
                            </recurringPrice>
                        </recurring>
                        <usages/>
                    </finalPhase>
                    <plansAllowedInBundle>-1</plansAllowedInBundle>
                </plan>
                <plan name="super-monthly" prettyName="super-monthly">
                    <product>Super</product>
                    <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
                    <initialPhases>
                        <phase type="TRIAL">
                            <duration>
<unit>DAYS</unit>
<number>30</number>
                            </duration>
                            <fixed type="ONE_TIME">
<fixedPrice/>
                            </fixed>
                            <usages/>
                        </phase>
                    </initialPhases>
                    <finalPhase type="EVERGREEN">
                        <duration>
                            <unit>UNLIMITED</unit>
                            <number>-1</number>
                        </duration>
                        <recurring>
                            <billingPeriod>MONTHLY</billingPeriod>
                            <recurringPrice>
<price>
    <currency>GBP</currency>
    <value>750.00</value>
</price>
<price>
    <currency>USD</currency>
    <value>1000.00</value>
</price>
                            </recurringPrice>
                        </recurring>
                        <usages/>
                    </finalPhase>
                    <plansAllowedInBundle>-1</plansAllowedInBundle>
                </plan>
            </plans>
            <priceLists>
                <defaultPriceList name="DEFAULT">
                    <plans>
                        <plan>sports-monthly</plan>
                        <plan>standard-monthly</plan>
                        <plan>super-monthly</plan>
                    </plans>
                </defaultPriceList>
            </priceLists>
        </version>
    </versions>
    <catalogName>SpyCarBasic</catalogName>
</catalogs>

<?xml version="1.0" encoding="UTF-8"?>
<catalogs>
   <versions>
      <version>
         <effectiveDate>2013-02-08T00:00:00Z</effectiveDate>
         <catalogName>Movies</catalogName>
         <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
         <currencies>
            <currency>USD</currency>
         </currencies>
         <units />
         <products>
            <product name="Basic">
               <category>BASE</category>
               <included />
               <available />
               <limits />
            </product>
         </products>
         <rules>
            <changePolicy>
               <changePolicyCase>
                  <policy>END_OF_TERM</policy>
               </changePolicyCase>
            </changePolicy>
            <changeAlignment>
               <changeAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </changeAlignmentCase>
            </changeAlignment>
            <cancelPolicy>
               <cancelPolicyCase>
                  <productCategory>BASE</productCategory>
                  <policy>END_OF_TERM</policy>
               </cancelPolicyCase>
               <cancelPolicyCase>
                  <policy>IMMEDIATE</policy>
               </cancelPolicyCase>
            </cancelPolicy>
            <createAlignment>
               <createAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </createAlignmentCase>
            </createAlignment>
            <billingAlignment>
               <billingAlignmentCase>
                  <alignment>ACCOUNT</alignment>
               </billingAlignmentCase>
            </billingAlignment>
            <priceList>
               <priceListCase>
                  <toPriceList>DEFAULT</toPriceList>
               </priceListCase>
            </priceList>
         </rules>
         <plans>
            <plan name="basic-monthly">
               <product>Basic</product>
               <initialPhases />
               <finalPhase type="EVERGREEN">
                  <duration>
                     <unit>UNLIMITED</unit>
                     <number>-1</number>
                  </duration>
                  <recurring>
                     <billingPeriod>MONTHLY</billingPeriod>
                     <recurringPrice>
                        <price>
                           <currency>USD</currency>
                           <value>1000.00</value>
                        </price>
                     </recurringPrice>
                  </recurring>
                  <usages />
               </finalPhase>
               <plansAllowedInBundle>-1</plansAllowedInBundle>
            </plan>
         </plans>
         <priceLists>
            <defaultPriceList name="DEFAULT">
               <plans>
                  <plan>basic-monthly</plan>
               </plans>
            </defaultPriceList>
         </priceLists>
      </version>
      <version>
         <effectiveDate>2013-02-08T00:00:01Z</effectiveDate>
         <catalogName>Movies</catalogName>
         <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
         <currencies>
            <currency>USD</currency>
         </currencies>
         <units />
         <products>
            <product name="Basic">
               <category>BASE</category>
               <included />
               <available />
               <limits />
            </product>
         </products>
         <rules>
            <changePolicy>
               <changePolicyCase>
                  <policy>END_OF_TERM</policy>
               </changePolicyCase>
            </changePolicy>
            <changeAlignment>
               <changeAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </changeAlignmentCase>
            </changeAlignment>
            <cancelPolicy>
               <cancelPolicyCase>
                  <productCategory>BASE</productCategory>
                  <policy>END_OF_TERM</policy>
               </cancelPolicyCase>
               <cancelPolicyCase>
                  <policy>IMMEDIATE</policy>
               </cancelPolicyCase>
            </cancelPolicy>
            <createAlignment>
               <createAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </createAlignmentCase>
            </createAlignment>
            <billingAlignment>
               <billingAlignmentCase>
                  <alignment>ACCOUNT</alignment>
               </billingAlignmentCase>
            </billingAlignment>
            <priceList>
               <priceListCase>
                  <toPriceList>DEFAULT</toPriceList>
               </priceListCase>
            </priceList>
         </rules>
         <plans>
            <plan name="basic-monthly">
               <product>Basic</product>
               <initialPhases>
                  <phase type="TRIAL">
                     <duration>
                        <unit>DAYS</unit>
                        <number>30</number>
                     </duration>
                     <fixed type="ONE_TIME">
                        <fixedPrice />
                     </fixed>
                     <usages />
                  </phase>
               </initialPhases>
               <finalPhase type="EVERGREEN">
                  <duration>
                     <unit>UNLIMITED</unit>
                     <number>-1</number>
                  </duration>
                  <recurring>
                     <billingPeriod>MONTHLY</billingPeriod>
                     <recurringPrice>
                        <price>
                           <currency>USD</currency>
                           <value>1000.00</value>
                        </price>
                     </recurringPrice>
                  </recurring>
                  <usages />
               </finalPhase>
               <plansAllowedInBundle>-1</plansAllowedInBundle>
            </plan>
         </plans>
         <priceLists>
            <defaultPriceList name="DEFAULT">
               <plans>
                  <plan>basic-monthly</plan>
               </plans>
            </defaultPriceList>
         </priceLists>
      </version>
   </versions>
   <catalogName>Movies</catalogName>
   <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
</catalogs>

<?xml version="1.0" encoding="UTF-8"?>
<catalogs>
   <versions>
      <version>
         <effectiveDate>2013-02-08T00:00:00Z</effectiveDate>
         <catalogName>Movies</catalogName>
         <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
         <currencies>
            <currency>USD</currency>
         </currencies>
         <units />
         <products>
            <product name="Basic">
               <category>BASE</category>
               <included />
               <available />
               <limits />
            </product>
         </products>
         <rules>
            <changePolicy>
               <changePolicyCase>
                  <policy>END_OF_TERM</policy>
               </changePolicyCase>
            </changePolicy>
            <changeAlignment>
               <changeAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </changeAlignmentCase>
            </changeAlignment>
            <cancelPolicy>
               <cancelPolicyCase>
                  <productCategory>BASE</productCategory>
                  <policy>END_OF_TERM</policy>
               </cancelPolicyCase>
               <cancelPolicyCase>
                  <policy>IMMEDIATE</policy>
               </cancelPolicyCase>
            </cancelPolicy>
            <createAlignment>
               <createAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </createAlignmentCase>
            </createAlignment>
            <billingAlignment>
               <billingAlignmentCase>
                  <alignment>ACCOUNT</alignment>
               </billingAlignmentCase>
            </billingAlignment>
            <priceList>
               <priceListCase>
                  <toPriceList>DEFAULT</toPriceList>
               </priceListCase>
            </priceList>
         </rules>
         <plans>
            <plan name="basic-monthly">
               <product>Basic</product>
               <initialPhases />
               <finalPhase type="EVERGREEN">
                  <duration>
                     <unit>UNLIMITED</unit>
                     <number>-1</number>
                  </duration>
                  <recurring>
                     <billingPeriod>MONTHLY</billingPeriod>
                     <recurringPrice>
                        <price>
                           <currency>USD</currency>
                           <value>1000.00</value>
                        </price>
                     </recurringPrice>
                  </recurring>
                  <usages />
               </finalPhase>
               <plansAllowedInBundle>-1</plansAllowedInBundle>
            </plan>
         </plans>
         <priceLists>
            <defaultPriceList name="DEFAULT">
               <plans>
                  <plan>basic-monthly</plan>
               </plans>
            </defaultPriceList>
         </priceLists>
      </version>
      <version>
         <effectiveDate>2013-02-08T00:00:01Z</effectiveDate>
         <catalogName>Movies</catalogName>
         <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
         <currencies>
            <currency>USD</currency>
         </currencies>
         <units />
         <products>
            <product name="Basic">
               <category>BASE</category>
               <included />
               <available />
               <limits />
            </product>
         </products>
         <rules>
            <changePolicy>
               <changePolicyCase>
                  <policy>END_OF_TERM</policy>
               </changePolicyCase>
            </changePolicy>
            <changeAlignment>
               <changeAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </changeAlignmentCase>
            </changeAlignment>
            <cancelPolicy>
               <cancelPolicyCase>
                  <productCategory>BASE</productCategory>
                  <policy>END_OF_TERM</policy>
               </cancelPolicyCase>
               <cancelPolicyCase>
                  <policy>IMMEDIATE</policy>
               </cancelPolicyCase>
            </cancelPolicy>
            <createAlignment>
               <createAlignmentCase>
                  <alignment>START_OF_BUNDLE</alignment>
               </createAlignmentCase>
            </createAlignment>
            <billingAlignment>
               <billingAlignmentCase>
                  <alignment>ACCOUNT</alignment>
               </billingAlignmentCase>
            </billingAlignment>
            <priceList>
               <priceListCase>
                  <toPriceList>DEFAULT</toPriceList>
               </priceListCase>
            </priceList>
         </rules>
         <plans>
            <plan name="basic-monthly">
               <product>Basic</product>
               <initialPhases>
                  <phase type="TRIAL">
                     <duration>
                        <unit>DAYS</unit>
                        <number>30</number>
                     </duration>
                     <fixed type="ONE_TIME">
                        <fixedPrice />
                     </fixed>
                     <usages />
                  </phase>
               </initialPhases>
               <finalPhase type="EVERGREEN">
                  <duration>
                     <unit>UNLIMITED</unit>
                     <number>-1</number>
                  </duration>
                  <recurring>
                     <billingPeriod>MONTHLY</billingPeriod>
                     <recurringPrice>
                        <price>
                           <currency>USD</currency>
                           <value>1000.00</value>
                        </price>
                     </recurringPrice>
                  </recurring>
                  <usages />
               </finalPhase>
               <plansAllowedInBundle>-1</plansAllowedInBundle>
            </plan>
         </plans>
         <priceLists>
            <defaultPriceList name="DEFAULT">
               <plans>
                  <plan>basic-monthly</plan>
               </plans>
            </defaultPriceList>
         </priceLists>
      </version>
   </versions>
   <catalogName>Movies</catalogName>
   <recurringBillingMode>IN_ADVANCE</recurringBillingMode>
</catalogs>

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	false	current date	requested date

Response

If successful, returns a status code of 200 and the catalog for the requested date in XML format.

Retrieve the catalog as JSON

This endpoint retrieves the Catalog for a requested date in JSON format. If there are multiple versions, the latest version with an effective date not later than the requested date is returned. If the effective date for all versions is greater than the requested date, the earliest version is returned. See the previous endpoint for examples.

HTTP Request

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

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/catalog"  

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

DateTime requestedDate = null;
UUID accountId = null;

Catalogs catalogsJson = catalogApi.getCatalogJson(requestedDate, 
                                                  accountId, 
                                                  requestOptions);

requested_date = nil

KillBillClient::Model::Catalog.get_tenant_catalog_json.(requested_date, 
                                                        options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_catalog_json(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "name": "SpyCarBasic",
    "effectiveDate": "2013-02-08T00:00:00.000+0000",
    "currencies": [
      "USD",
      "GBP"
    ],
    "units": [],
    "products": [
      {
        "type": "ADD_ON",
        "name": "Super",
        "prettyName": "Super",
        "plans": [
          {
            "name": "super-monthly",
            "prettyName": "super-monthly",
            "billingPeriod": "MONTHLY",
            "phases": [
              {
                "type": "TRIAL",
                "prices": [],
                "fixedPrices": [],
                "duration": {
                  "unit": "DAYS",
                  "number": 30
                },
                "usages": []
              },
              {
                "type": "EVERGREEN",
                "prices": [
                  {
                    "currency": "GBP",
                    "value": 750
                  },
                  {
                    "currency": "USD",
                    "value": 1000
                  }
                ],
                "fixedPrices": [],
                "duration": {
                  "unit": "UNLIMITED",
                  "number": -1
                },
                "usages": []
              }
            ]
          }
        ],
        "included": [],
        "available": []
      },
      {
        "type": "BASE",
        "name": "Standard",
        "prettyName": "Standard",
        "plans": [
          {
            "name": "standard-monthly",
            "prettyName": "standard-monthly",
            "billingPeriod": "MONTHLY",
            "phases": [
              {
                "type": "TRIAL",
                "prices": [],
                "fixedPrices": [],
                "duration": {
                  "unit": "DAYS",
                  "number": 30
                },
                "usages": []
              },
              {
                "type": "EVERGREEN",
                "prices": [
                  {
                    "currency": "GBP",
                    "value": 75
                  },
                  {
                    "currency": "USD",
                    "value": 100
                  }
                ],
                "fixedPrices": [],
                "duration": {
                  "unit": "UNLIMITED",
                  "number": -1
                },
                "usages": []
              }
            ]
          }
        ],
        "included": [],
        "available": []
      },
      {
        "type": "BASE",
        "name": "Sports",
        "prettyName": "Sports",
        "plans": [
          {
            "name": "sports-monthly",
            "prettyName": "sports-monthly",
            "billingPeriod": "MONTHLY",
            "phases": [
              {
                "type": "TRIAL",
                "prices": [],
                "fixedPrices": [],
                "duration": {
                  "unit": "DAYS",
                  "number": 30
                },
                "usages": []
              },
              {
                "type": "EVERGREEN",
                "prices": [
                  {
                    "currency": "GBP",
                    "value": 375
                  },
                  {
                    "currency": "USD",
                    "value": 500
                  }
                ],
                "fixedPrices": [],
                "duration": {
                  "unit": "UNLIMITED",
                  "number": -1
                },
                "usages": []
              }
            ]
          }
        ],
        "included": [],
        "available": []
      }
    ],
    "priceLists": [
      {
        "name": "DEFAULT",
        "plans": [
          "sports-monthly",
          "standard-monthly",
          "super-monthly"
        ]
      }
    ]
  }
]

class Catalog {
    name: Firearms
    effectiveDate: 2011-01-01T00:00:00.000Z
    currencies: [USD, EUR, GBP]
    units: [class Unit {
        name: bullets
        prettyName: bullets
    }, class Unit {
        name: stones
        prettyName: stones
    }]
    products: [class Product {
        type: BASE
        name: Assault-Rifle
        prettyName: Assault-Rifle
        plans: [class Plan {
            name: assault-rifle-annual
            prettyName: assault-rifle-annual
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 5999.95
                }, class Price {
                    currency: EUR
                    value: 3499.95
                }, class Price {
                    currency: GBP
                    value: 3999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: assault-rifle-annual-gunclub-discount
            prettyName: assault-rifle-annual-gunclub-discount
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 99.95
                }, class Price {
                    currency: EUR
                    value: 99.95
                }, class Price {
                    currency: GBP
                    value: 99.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 6
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 5999.95
                }, class Price {
                    currency: EUR
                    value: 3499.95
                }, class Price {
                    currency: GBP
                    value: 3999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: assault-rifle-annual-rescue
            prettyName: assault-rifle-annual-rescue
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 5999.95
                }, class Price {
                    currency: EUR
                    value: 3499.95
                }, class Price {
                    currency: GBP
                    value: 3999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: YEARS
                    number: 1
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 5999.95
                }, class Price {
                    currency: EUR
                    value: 3499.95
                }, class Price {
                    currency: GBP
                    value: 3999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: assault-rifle-monthly
            prettyName: assault-rifle-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 599.95
                }, class Price {
                    currency: EUR
                    value: 349.95
                }, class Price {
                    currency: GBP
                    value: 399.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: [Cleaning, Telescopic-Scope]
        available: [Bullets, Laser-Scope]
    }, class Product {
        type: ADD_ON
        name: Holster
        prettyName: Holster
        plans: [class Plan {
            name: holster-monthly-regular
            prettyName: holster-monthly-regular
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: holster-monthly-special
            prettyName: holster-monthly-special
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: ADD_ON
        name: Refurbish-Maintenance
        prettyName: Refurbish-Maintenance
        plans: [class Plan {
            name: refurbish-maintenance
            prettyName: refurbish-maintenance
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: FIXEDTERM
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: [class Price {
                    currency: USD
                    value: 599.95
                }, class Price {
                    currency: EUR
                    value: 599.95
                }, class Price {
                    currency: GBP
                    value: 599.95
                }]
                duration: class Duration {
                    unit: MONTHS
                    number: 12
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: BASE
        name: Trebuchet
        prettyName: Trebuchet
        plans: [class Plan {
            name: trebuchet-usage-in-arrear
            prettyName: Trebuchet Monthly Plan
            billingPeriod: NO_BILLING_PERIOD
            phases: [class Phase {
                type: EVERGREEN
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: [class Usage {
                    billingPeriod: MONTHLY
                    tiers: [class Tier {
                        limits: [class Limit {
                            unit: stones
                            max: 100.0
                            min: -1.0
                        }]
                        fixedPrice: []
                        recurringPrice: [class Price {
                            currency: USD
                            value: 100
                        }]
                        blocks: []
                    }, class Tier {
                        limits: [class Limit {
                            unit: stones
                            max: -1.0
                            min: -1.0
                        }]
                        fixedPrice: []
                        recurringPrice: [class Price {
                            currency: USD
                            value: 1000
                        }]
                        blocks: []
                    }]
                }]
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: BASE
        name: Blowdart
        prettyName: Blowdart
        plans: [class Plan {
            name: blowdart-monthly
            prettyName: blowdart-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 9.95
                }, class Price {
                    currency: EUR
                    value: 9.95
                }, class Price {
                    currency: GBP
                    value: 9.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 6
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: GBP
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: blowdart-monthly-notrial
            prettyName: blowdart-monthly-notrial
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: GBP
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: blowdart-monthly-trial
            prettyName: blowdart-monthly-trial
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: GBP
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: ADD_ON
        name: Extra-Ammo
        prettyName: Extra-Ammo
        plans: [class Plan {
            name: extra-ammo-monthly
            prettyName: extra-ammo-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 999.95
                }, class Price {
                    currency: EUR
                    value: 499.95
                }, class Price {
                    currency: GBP
                    value: 999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: BASE
        name: Shotgun
        prettyName: Shotgun
        plans: [class Plan {
            name: shotgun-annual
            prettyName: shotgun-annual
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 2399.95
                }, class Price {
                    currency: EUR
                    value: 1499.95
                }, class Price {
                    currency: GBP
                    value: 1699.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: shotgun-annual-gunclub-discount
            prettyName: shotgun-annual-gunclub-discount
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 19.95
                }, class Price {
                    currency: EUR
                    value: 49.95
                }, class Price {
                    currency: GBP
                    value: 69.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 6
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 2399.95
                }, class Price {
                    currency: EUR
                    value: 1499.95
                }, class Price {
                    currency: GBP
                    value: 1699.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: shotgun-monthly
            prettyName: Shotgun Monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 249.95
                }, class Price {
                    currency: EUR
                    value: 149.95
                }, class Price {
                    currency: GBP
                    value: 169.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: [Cleaning]
        available: [Bullets, Holster, Laser-Scope, Telescopic-Scope]
    }, class Product {
        type: ADD_ON
        name: Cleaning
        prettyName: Cleaning
        plans: [class Plan {
            name: cleaning-monthly
            prettyName: cleaning-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 2.95
                }, class Price {
                    currency: EUR
                    value: 1.95
                }, class Price {
                    currency: GBP
                    value: 0.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: ADD_ON
        name: Laser-Scope
        prettyName: Laser-Scope
        plans: [class Plan {
            name: laser-scope-monthly
            prettyName: laser-scope-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 999.95
                }, class Price {
                    currency: EUR
                    value: 499.95
                }, class Price {
                    currency: GBP
                    value: 999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 1
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 1999.95
                }, class Price {
                    currency: EUR
                    value: 1499.95
                }, class Price {
                    currency: GBP
                    value: 1999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: STANDALONE
        name: Knife
        prettyName: Knife
        plans: [class Plan {
            name: knife-monthly-notrial
            prettyName: knife-monthly-notrial
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: GBP
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: BASE
        name: Pistol
        prettyName: Pistol
        plans: [class Plan {
            name: pistol-annual
            prettyName: pistol-annual
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-annual-gunclub-discount
            prettyName: pistol-annual-gunclub-discount
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 9.95
                }, class Price {
                    currency: EUR
                    value: 9.95
                }, class Price {
                    currency: GBP
                    value: 9.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 6
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-annual-gunclub-discount-notrial
            prettyName: pistol-annual-gunclub-discount-notrial
            billingPeriod: ANNUAL
            phases: [class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 9.95
                }, class Price {
                    currency: EUR
                    value: 9.95
                }, class Price {
                    currency: GBP
                    value: 9.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 6
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 199.95
                }, class Price {
                    currency: EUR
                    value: 199.95
                }, class Price {
                    currency: GBP
                    value: 199.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-monthly
            prettyName: pistol-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: GBP
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: USD
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-monthly-fixedterm
            prettyName: pistol-monthly-fixedterm
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: FIXEDTERM
                prices: [class Price {
                    currency: GBP
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: USD
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 12
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-monthly-notrial
            prettyName: pistol-monthly-notrial
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 19.95
                }, class Price {
                    currency: EUR
                    value: 19.95
                }, class Price {
                    currency: GBP
                    value: 19.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-quarterly
            prettyName: pistol-quarterly
            billingPeriod: QUARTERLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: GBP
                    value: 69.95
                }, class Price {
                    currency: EUR
                    value: 69.95
                }, class Price {
                    currency: USD
                    value: 69.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-thirty-days
            prettyName: pistol-thirty-days
            billingPeriod: THIRTY_DAYS
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: GBP
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: USD
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }, class Plan {
            name: pistol-weekly
            prettyName: pistol-weekly
            billingPeriod: WEEKLY
            phases: [class Phase {
                type: TRIAL
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: DAYS
                    number: 30
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: GBP
                    value: 29.95
                }, class Price {
                    currency: EUR
                    value: 29.95
                }, class Price {
                    currency: USD
                    value: 29.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: [Bullets, Cleaning, Refurbish-Maintenance]
    }, class Product {
        type: ADD_ON
        name: Bullets
        prettyName: Bullets
        plans: [class Plan {
            name: bullets-usage-in-arrear
            prettyName: Bullet Monthly Plan
            billingPeriod: NO_BILLING_PERIOD
            phases: [class Phase {
                type: EVERGREEN
                prices: []
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: [class Usage {
                    billingPeriod: MONTHLY
                    tiers: [class Tier {
                        limits: []
                        fixedPrice: []
                        recurringPrice: []
                        blocks: [class TieredBlock {
                            unit: bullets
                            size: 100.0
                            max: 10.0
                            prices: [class Price {
                                currency: USD
                                value: 2.95
                            }, class Price {
                                currency: EUR
                                value: 1.95
                            }, class Price {
                                currency: GBP
                                value: 0.95
                            }]
                        }]
                    }, class Tier {
                        limits: []
                        fixedPrice: []
                        recurringPrice: []
                        blocks: [class TieredBlock {
                            unit: bullets
                            size: 1000.0
                            max: 100.0
                            prices: [class Price {
                                currency: USD
                                value: 5.95
                            }, class Price {
                                currency: EUR
                                value: 4.95
                            }, class Price {
                                currency: GBP
                                value: 3.95
                            }]
                        }]
                    }]
                }]
            }]
        }]
        included: []
        available: []
    }, class Product {
        type: ADD_ON
        name: Telescopic-Scope
        prettyName: Telescopic-Scope
        plans: [class Plan {
            name: telescopic-scope-monthly
            prettyName: telescopic-scope-monthly
            billingPeriod: MONTHLY
            phases: [class Phase {
                type: DISCOUNT
                prices: [class Price {
                    currency: USD
                    value: 399.95
                }, class Price {
                    currency: EUR
                    value: 299.95
                }, class Price {
                    currency: GBP
                    value: 399.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: MONTHS
                    number: 1
                }
                usages: []
            }, class Phase {
                type: EVERGREEN
                prices: [class Price {
                    currency: USD
                    value: 999.95
                }, class Price {
                    currency: EUR
                    value: 499.95
                }, class Price {
                    currency: GBP
                    value: 999.95
                }]
                fixedPrices: []
                duration: class Duration {
                    unit: UNLIMITED
                    number: -1
                }
                usages: []
            }]
        }]
        included: []
        available: []
    }]
    priceLists: [class PriceList {
        name: DEFAULT
        plans: [assault-rifle-annual, assault-rifle-monthly, blowdart-monthly, bullets-usage-in-arrear, cleaning-monthly, extra-ammo-monthly, holster-monthly-regular, holster-monthly-special, laser-scope-monthly, pistol-annual, pistol-monthly, pistol-quarterly, pistol-thirty-days, pistol-weekly, refurbish-maintenance, shotgun-annual, shotgun-monthly, telescopic-scope-monthly, trebuchet-usage-in-arrear]
    }, class PriceList {
        name: gunclubDiscount
        plans: [assault-rifle-annual-gunclub-discount, pistol-annual-gunclub-discount, shotgun-annual-gunclub-discount]
    }, class PriceList {
        name: gunclubDiscountNoTrial
        plans: [pistol-annual-gunclub-discount-notrial]
    }, class PriceList {
        name: rescue
        plans: [assault-rifle-annual-rescue]
    }, class PriceList {
        name: fixedTerm
        plans: [pistol-monthly-fixedterm]
    }, class PriceList {
        name: notrial
        plans: [blowdart-monthly-notrial, knife-monthly-notrial, pistol-monthly-notrial]
    }, class PriceList {
        name: trial
        plans: [blowdart-monthly-trial]
    }]
}

[
   {
      "name":"Movies",
      "effectiveDate":"2013-02-08T00:00:00.000+0000",
      "currencies":[
         "USD"
      ],
      "units":[

      ],
      "products":[
         {
            "type":"BASE",
            "name":"Basic",
            "prettyName":"Basic",
            "plans":[
               {
                  "name":"basic-monthly",
                  "prettyName":"basic-monthly",
                  "billingPeriod":"MONTHLY",
                  "phases":[
                     {
                        "type":"EVERGREEN",
                        "prices":[
                           {
                              "currency":"USD",
                              "value":1000.0
                           }
                        ],
                        "fixedPrices":[

                        ],
                        "duration":{
                           "unit":"UNLIMITED",
                           "number":-1
                        },
                        "usages":[

                        ]
                     }
                  ]
               }
            ],
            "included":[

            ],
            "available":[

            ]
         }
      ],
      "priceLists":[
         {
            "name":"DEFAULT",
            "plans":[
               "basic-monthly"
            ]
         }
      ]
   }
]

[{'currencies': ['USD', 'GBP'],
 'effective_date': datetime.datetime(2013, 2, 8, 0, 0, tzinfo=tzutc()),
 'name': 'SpyCarBasic',
 'price_lists': [{'name': 'DEFAULT',
                  'plans': ['sports-monthly',
                            'standard-monthly',
                            'super-monthly']}],
 'products': [{'available': [],
               'included': [],
               'name': 'Super',
               'plans': [{'billing_period': 'MONTHLY',
                          'name': 'super-monthly',
                          'phases': [{'duration': {'number': 30,
                                                   'unit': 'DAYS'},
                                      'fixed_prices': [],
                                      'prices': [],
                                      'type': 'TRIAL',
                                      'usages': []},
                                     {'duration': {'number': -1,
                                                   'unit': 'UNLIMITED'},
                                      'fixed_prices': [],
                                      'prices': [{'currency': 'GBP',
                                                  'value': 750.0},
                                                 {'currency': 'USD',
                                                  'value': 1000.0}],
                                      'type': 'EVERGREEN',
                                      'usages': []}],
                          'pretty_name': 'super-monthly'}],
               'pretty_name': 'Super',
               'type': 'BASE'},
              {'available': [],
               'included': [],
               'name': 'Standard',
               'plans': [{'billing_period': 'MONTHLY',
                          'name': 'standard-monthly',
                          'phases': [{'duration': {'number': 30,
                                                   'unit': 'DAYS'},
                                      'fixed_prices': [],
                                      'prices': [],
                                      'type': 'TRIAL',
                                      'usages': []},
                                     {'duration': {'number': -1,
                                                   'unit': 'UNLIMITED'},
                                      'fixed_prices': [],
                                      'prices': [{'currency': 'GBP',
                                                  'value': 75.0},
                                                 {'currency': 'USD',
                                                  'value': 100.0}],
                                      'type': 'EVERGREEN',
                                      'usages': []}],
                          'pretty_name': 'standard-monthly'}],
               'pretty_name': 'Standard',
               'type': 'BASE'},

{'available': [],
               'included': [],
               'name': 'Sports',
               'plans': [{'billing_period': 'MONTHLY',
                          'name': 'sports-monthly',
                          'phases': [{'duration': {'number': 30,
                                                   'unit': 'DAYS'},
                                      'fixed_prices': [],
                                      'prices': [],
                                      'type': 'TRIAL',
                                      'usages': []},
                                     {'duration': {'number': -1,
                                                   'unit': 'UNLIMITED'},
                                      'fixed_prices': [],
                                      'prices': [{'currency': 'GBP',
                                                  'value': 375.0},
                                                 {'currency': 'USD',
                                                  'value': 500.0}],
                                      'type': 'EVERGREEN',
                                      'usages': []}],
                          'pretty_name': 'sports-monthly'}],
               'pretty_name': 'Sports',
               'type': 'BASE'}],
 'units': []}]

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	false	current date	requested date

Response

if successful, returns a status code of 200 and the full catalog for the requested date in JSON format.

Retrieve a list of catalog versions

Return a list of the effective dates for all available catalogs versions for this tenant.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/versions

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/catalog/versions"

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

UUID accountId = null;

List<DateTime> versions = catalogApi.getCatalogVersions(accountId, requestOptions);

KillBillClient::Model::Catalog.get_tenant_catalog_versions(options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_catalog_versions(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  "2013-02-08T00:00:00.000Z"
]

2013-02-08T00:00:00.000Z

["2013-02-08T00:00:00.000Z"]

[datetime.datetime(2013, 2, 8, 0, 0, tzinfo=tzutc())]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a comma-separated list of ISO date strings giving the effective date for each available catalog version.

Retrieve available base plans

Returns a list of available base products and associated plans. Each object returned specifies a product, a priceList, a planselected from the pricelist, and pricing information for the final phase of the plan.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/availableBasePlans

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/catalog/availableBasePlans"   

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

UUID accountId = null;

List<PlanDetail> basePlans = catalogApi.getAvailableBasePlans(accountId, requestOptions);

KillBillClient::Model::Catalog.available_base_plans(options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_available_base_plans(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "product": "Sports",
    "plan": "sports-monthly",
    "priceList": "DEFAULT",
    "finalPhaseBillingPeriod": "MONTHLY",
    "finalPhaseRecurringPrice": [
      {
        "currency": "GBP",
        "value": 375
      },
      {
        "currency": "USD",
        "value": 500
      }
    ]
  },
  {
    "product": "Standard",
    "plan": "standard-monthly",
    "priceList": "DEFAULT",
    "finalPhaseBillingPeriod": "MONTHLY",
    "finalPhaseRecurringPrice": [
      {
        "currency": "GBP",
        "value": 75
      },
      {
        "currency": "USD",
        "value": 100
      }
    ]
  }
]

//First element of the list
class PlanDetail {
    product: Assault-Rifle
    plan: assault-rifle-annual
    priceList: DEFAULT
    finalPhaseBillingPeriod: ANNUAL
    finalPhaseRecurringPrice: [class Price {
        currency: USD
        value: 5999.95
    }, class Price {
        currency: EUR
        value: 3499.95
    }, class Price {
        currency: GBP
        value: 3999.95
    }]
}

[
   {
      "product":"Basic",
      "plan":"basic-annual",
      "finalPhaseBillingPeriod":"ANNUAL",
      "priceList":"DEFAULT",
      "finalPhaseRecurringPrice":[
         {
            "currency":"USD",
            "value":10000.0
         }
      ]
   },
   {
      "product":"Basic",
      "plan":"basic-monthly",
      "finalPhaseBillingPeriod":"MONTHLY",
      "priceList":"DEFAULT",
      "finalPhaseRecurringPrice":[
         {
            "currency":"USD",
            "value":1000.0
         }
      ]
   }
]

[{'final_phase_billing_period': 'MONTHLY',
 'final_phase_recurring_price': [{'currency': 'GBP', 'value': 375.0},
                                 {'currency': 'USD', 'value': 500.0}],
 'plan': 'sports-monthly',
 'price_list': 'DEFAULT',
 'product': 'Sports'}, {'final_phase_billing_period': 'MONTHLY',
 'final_phase_recurring_price': [{'currency': 'GBP', 'value': 75.0},
                                 {'currency': 'USD', 'value': 100.0}],
 'plan': 'standard-monthly',
 'price_list': 'DEFAULT',
 'product': 'Standard'}, {'final_phase_billing_period': 'MONTHLY',
 'final_phase_recurring_price': [{'currency': 'GBP', 'value': 750.0},
                                 {'currency': 'USD', 'value': 1000.0}],
 'plan': 'super-monthly',
 'price_list': 'DEFAULT',
 'product': 'Super'}]

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of objects representing the available base products and plans.

Retrieve available add-ons for a given product

Returns a list of available add-on products, if any, for a specified base product, and for a specified price list or all price lists. Each object returned specifies a product, a priceList, a plan selected from the pricelist, and pricing information for the final phase of the plan.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/availableAddons

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/catalog/availableAddons"  

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

String baseProductName = "Bullets";
String priceListName = null;
UUID accountId = null;

List<PlanDetail> availableAddons = catalogApi.getAvailableAddons(baseProductName, 
                                                                 priceListName, 
                                                                 accountId, 
                                                                 requestOptions);

base_product_name = 'Basic'
KillBillClient::Model::Catalog.available_addons(base_product_name, 
                                                options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_available_addons(api_key, 
                                api_secret, 
                                base_product_name='Basic')

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
   {
      "product":"Basic",
      "plan":"basic-annual",
      "finalPhaseBillingPeriod":"ANNUAL",
      "priceList":"DEFAULT",
      "finalPhaseRecurringPrice":[
         {
            "currency":"USD",
            "value":10000.0
         }
      ]
   }
]

//First element of the list
class PlanDetail {
    product: Bullets
    plan: bullets-usage-in-arrear
    priceList: DEFAULT
    finalPhaseBillingPeriod: NO_BILLING_PERIOD
    finalPhaseRecurringPrice: []
}

[
   {
      "product":"Basic",
      "plan":"basic-annual",
      "finalPhaseBillingPeriod":"ANNUAL",
      "priceList":"DEFAULT",
      "finalPhaseRecurringPrice":[
         {
            "currency":"USD",
            "value":10000.0
         }
      ]
   }
]

[{'product': 'Basic',
  'plan': 'basic-annual',
  'final_phase_billing_period': 'ANNUAL',
  'price_list': 'DEFAULT',
  'final_phase_recurring_price':[{'currency': 'USD',
                                  'value': 10000.0}]
}]

Query Parameters

Name	Type	Required	Default	Description
baseProductName	string	true	none	base product name
priceListName	string	false	all price lists	price list name

Response

If successful, returns a status code of 200 and a list of objects representing available add-on products.

Delete all versions of a per tenant catalog

Delete all per-tenant catalog versions. The tenant reverts to the system default catalog.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/catalog

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/catalog"  

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

catalogApi.deleteCatalog(requestOptions);

KillBillClient::Model::Catalog.delete_catalog(user,
                                              reason,
                                              comment,
                                              options)

catalogApi = killbill.api.CatalogApi()

catalogApi.delete_catalog(created_by, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content

no content

no content

no content

Query Parameters

None.

Response

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

Subscription info

These endpoints return information concerning a particular subscription. They select from the catalog only the items (such as plan, phase, or products) that currently apply to the specified subscription.

Retrieve the phase for a given subscription and date

This API returns information about the current Phase associated with a given subscription. The record returned includes the phase type and information about pricing, duration, and usage.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/phase

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/catalog/phase?subscriptionId=8ab101b6-15e8-433b-b4f7-f99eeaa56a77&requestedDate=2018-7-18"    

TODO

requested_date = nil
KillBillClient::Model::Catalog.get_catalog_phase(subscription_id, 
                                                 requested_date, 
                                                 options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_phase_for_subscription_and_date(api_key, 
                                               api_secret, 
                                               subscription_id=subscription_id)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "type": "TRIAL",
  "prices": [],
  "fixedPrices": [],
  "duration": {
    "unit": "DAYS",
    "number": 30
  },
  "usages": []
} 

TODO

{
   "duration":{
      "number":30,
      "unit":"DAYS"
   },
   "fixed_prices":[

   ],
   "prices":[

   ],
   "type":"TRIAL",
   "usages":[

   ]
}

{'duration': {'number': 30, 'unit': 'DAYS'},
 'fixed_prices': [],
 'prices': [],
 'type': 'TRIAL',
 'usages': []}

Query Parameters

Name	Type	Required	Default	Description
subscriptionId	string	true	none	subscription id
requestedDate	string	false	current date	requested date

Response

If successful, returns a status code of 200 and a record for the current phase.

Retrieve the plan for a given subscription and date

This API returns information about the current Plan associated with a given subscription. The record returned includes the plan name and information for each phase of the plan.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/plan

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/catalog/plan?subscriptionId=8ab101b6-15e8-433b-b4f7-f99eeaa56a77&requestedDate=2018-7-18" 

TODO

requested_date = nil
KillBillClient::Model::Catalog.get_catalog_plan(subscription_id, 
                                                requested_date, 
                                                options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_plan_for_subscription_and_date(api_key, 
                                              api_secret, 
                                              subscription_id=subscription_id)

Example Response:

{
  "name": "standard-monthly",
  "prettyName": "standard-monthly",
  "billingPeriod": "MONTHLY",
  "phases": [
    {
      "type": "TRIAL",
      "prices": [],
      "fixedPrices": [],
      "duration": {
        "unit": "DAYS",
        "number": 30
      },
      "usages": []
    },
    {
      "type": "EVERGREEN",
      "prices": [
        {
          "currency": "GBP",
          "value": 75
        },
        {
          "currency": "USD",
          "value": 100
        }
      ],
      "fixedPrices": [],
      "duration": {
        "unit": "UNLIMITED",
        "number": -1
      },
      "usages": []
    }
  ]
}

TODO

{
   "billing_period":"MONTHLY",
   "name":"standard-monthly",
   "phases":[
      {
         "duration":{
            "number":30,
            "unit":"DAYS"
         },
         "fixed_prices":[

         ],
         "prices":[

         ],
         "type":"TRIAL",
         "usages":[

         ]
      },
      {
         "duration":{
            "number":-1,
            "unit":"UNLIMITED"
         },
         "fixed_prices":[

         ],
         "prices":[
            {
               "currency":"GBP",
               "value":75.0
            },
            {
               "currency":"USD",
               "value":100.0
            }
         ],
         "type":"EVERGREEN",
         "usages":[

         ]
      }
   ],
   "pretty_name":"standard-monthly"
}

{'billing_period': 'MONTHLY',
 'name': 'standard-monthly',
 'phases': [{'duration': {'number': 30, 'unit': 'DAYS'},
             'fixed_prices': [],
             'prices': [],
             'type': 'TRIAL',
             'usages': []},
            {'duration': {'number': -1, 'unit': 'UNLIMITED'},
             'fixed_prices': [],
             'prices': [{'currency': 'GBP', 'value': 75.0},
                        {'currency': 'USD', 'value': 100.0}],
             'type': 'EVERGREEN',
             'usages': []}],
 'pretty_name': 'standard-monthly'}

Query Parameters

Name	Type	Required	Default	Description
subscriptionId	string	true	none	subscription id
requestedDate	string	false	current date	requested date

Response

If successful, returns a status code of 200 and a record for the plan for this subscription.

Retrieve the priceList for a given subscription and date

This API returns information about the current priceList associated with a given subscription. The record returned includes the price list name and the list of plans on this list.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/priceList

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/catalog/priceList?subscriptionId=8ab101b6-15e8-433b-b4f7-f99eeaa56a77&requestedDate=2018-7-18"    

TODO

requested_date = nil
KillBillClient::Model::Catalog.get_catalog_price_list(subscription_id, 
                                                      requested_date, 
                                                      options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_price_list_for_subscription_and_date(api_key, 
                                                    api_secret, 
                                                    subscription_id=subscription_id)

Example Response:

{
  "name": "DEFAULT",
  "plans": [
    "sports-monthly",
    "standard-monthly",
    "super-monthly"
  ]
}

TODO

{
   "name":"DEFAULT",
   "plans":[
      "sports-monthly",
      "standard-monthly",
      "super-monthly"
   ]
}

{'name': 'DEFAULT',
 'plans': ['sports-monthly', 'standard-monthly', 'super-monthly']}

Query Parameters

Name	Type	Required	Default	Description
subscriptionId	string	true	none	subscription id
requestedDate	string	false	current date	requested date

Response

If successful, returns a status code of 200 and a record for the price list for this subscription.

Retrieve product for a given subscription and date

This API returns information about the product associated with a given subscription. The record returned includes the product names, available plans, items included, and available add-ons.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/catalog/product

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/catalog/product?subscriptionId=8ab101b6-15e8-433b-b4f7-f99eeaa56a77&requestedDate=2018-7-18"  

TODO

requested_date = nil
KillBillClient::Model::Catalog.get_catalog_product(subscription_id, 
                                                   requested_date, 
                                                   options)

catalogApi = killbill.api.CatalogApi()

catalogApi.get_product_for_subscription_and_date(api_key, 
                                                 api_secret, 
                                                 subscription_id=subscription_id)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "type": "BASE",
  "name": "Standard",
  "prettyName": "Standard",
  "plans": [],
  "included": [],
  "available": []
}

TODO

{
   "available":[

   ],
   "included":[

   ],
   "name":"Standard",
   "plans":[

   ],
   "pretty_name":"Standard",
   "type":"BASE"
}

{'available': [],
 'included': [],
 'name': 'Standard',
 'plans': [],
 'pretty_name': 'Standard',
 'type': 'BASE'}

Query Parameters

Name	Type	Required	Default	Description
subscriptionId	string	true	none	subscription id
requestedDate	string	false	current date	requested date

Response

If successful, returns a status code of 200 and a record for the product for this subscription.

Simple Plan

We provide a more basic level of APIs as a quick way to add a Plan into an existing version of the catalog. The intent is mostly to help getting started with Kill Bill by abstracting away more complex topics such as alignements, rules, ... The functionality is exposed on our admin UI (KAUI) to provide a simple graphical way to configure a simple catalog and get started quickly.

One can directly use our Simple Plan API to add new Plans without the need to create an initial catalog version: If there is no existing catalog version for the tenant, the system will create such an initial version when the first plan is added; otherwise, the system will use the existing active catalog version to add the new plan (but it will not create a new catalog version).

Note that because the Simple Plan API is just an abstraction on top of the more complex XML based APIs, one can start with such Simple Plan API, and then download the resulting XML, and edit such catalog by hand (to add entries, modify default rules, ...).

A simple plan has the following limitations:

• In-advance billing only
• Limited to one RECURRING phase and an optional $0 TRIAL phase
• No suport for fixed price

Once a simple plan has been uploaded, one can retrieve the associated XML, edit it to configure additional aspects, and then upload a new version of this catalog. So, this functionality can also be a stepping stone to a full catalog configuration.

Add a simple plan

Add a (simple) Plan into the current version of the Catalog associated with the tenant.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/catalog/simplePlan

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 '{ "planId": "basic-annual", "productName": "Basic", "productCategory": "BASE", "currency": "USD", "amount": 1000, "billingPeriod": "ANNUAL", "trialLength": 0, "trialTimeUnit": "UNLIMITED"}' \
    "http://localhost:8080/1.0/kb/catalog/simplePlan"

import org.killbill.billing.client.api.gen.CatalogApi;
protected CatalogApi catalogApi;

String planId = "foo-monthly";
String productName = "Foo";
Integer trialLength = 0;

SimplePlan body = new SimplePlan(planId, 
                                 productName, 
                                 ProductCategory.BASE, 
                                 Currency.USD, 
                                 BigDecimal.TEN, 
                                 BillingPeriod.MONTHLY, 
                                 trialLength, 
                                 TimeUnit.UNLIMITED, 
                                 ImmutableList.<String>of())

catalogApi.addSimplePlan(body, requestOptions);

simple_plan                  = KillBillClient::Model::SimplePlanAttributes.new
simple_plan.plan_id          = 'basic-annual'
simple_plan.product_name     = 'Basic'
simple_plan.product_category = 'BASE'
simple_plan.currency         = 'USD'
simple_plan.amount           = 10000.00
simple_plan.billing_period   = 'ANNUAL'
simple_plan.trial_length     = 0
simple_plan.trial_time_unit  = 'UNLIMITED'

KillBillClient::Model::Catalog.add_tenant_catalog_simple_plan(simple_plan,
                                                              user,
                                                              reason,
                                                              comment,
                                                              options)

catalogApi = killbill.api.CatalogApi()
body = SimplePlan(plan_id='basic-annual',
                  product_name='Basic',
                  product_category='BASE',
                  currency='USD',
                  amount=10000.00,
                  billing_period='ANNUAL',
                  trial_length=0,
                  trial_time_unit='UNLIMITED')

catalogApi.add_simple_plan(body, created_by, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/catalog
< Content-Type: application/json
< Content-Length: 0

TODO

no content

no content

Request Body

Provides the content for the plan in JSON form. This should be very simple. Note that the "planId" becomes the planName attribute. For example:

{ "planId": "newplan", "productName": "myitem", "productCategory": "BASE", "currency": "USD", "amount": 0, "billingPeriod": "DAILY", "trialLength": 0, "trialTimeUnit": "DAYS", "availableBaseProducts": [] }

Query Parameters

None.

Response

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

Account

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

Account Resource

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

The attributes contained in the account resource are the following:

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

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

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

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

Accounts

Create an Account

Create a new customer Account.

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "name": "John Doe", "email": "john@laposte.com", "currency": "USD"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts" 

import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

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

Account result = accountApi.createAccount(body, requestOptions);

account = KillBillClient::Model::Account.new
account.name = "John Doe"
account.email = "john@laposte.com"
account.currency = "USD"

account.create(user, reason, comment, options)

accountApi = killbill.api.AccountApi()
created_by = 'example'
body = Account(name='John Doe', 
               email='john@laposte.com', 
               currency='USD')

accountApi.create_account(body, 
                          created_by, 
                          api_key, 
                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/accounts/a8984103-b8e1-47cc-9914-4b1c4f9dbeab
< Content-Type: application/json
< Content-Length: 0

class Account {
    org.killbill.billing.client.model.gen.Account@3f77a367
    accountId: e1342e5c-db2a-4439-b52c-8597fde4390f
    name: John Doe
    firstNameLength: null
    externalKey: e1342e5c-db2a-4439-b52c-8597fde4390f
    email: john@laposte.com
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: null
    isPaymentDelegatedToParent: false
    paymentMethodId: null
    referenceTime: 2012-08-25T00:02:47.000Z
    timeZone: UTC
    address1: null
    address2: null
    postalCode: null
    company: null
    city: null
    state: null
    country: null
    locale: null
    phone: null
    notes: null
    isMigrated: false
    accountBalance: null
    accountCBA: null
    auditLogs: []
}

{
   "accountId":"87dccc88-f504-493e-a05f-9b4a702c3add",
   "name":"John Doe",
   "externalKey":"87dccc88-f504-493e-a05f-9b4a702c3add",
   "email":"john@laposte.com",
   "billCycleDayLocal":0,
   "currency":"USD",
   "isPaymentDelegatedToParent":false,
   "timeZone":"UTC",
   "auditLogs":[]
}

no content

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/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");
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 = "e8877928-0226-488d-9272-07a5e66d897f"
with_balance = false
with_balance_and_cba = false
account = KillBillClient::Model::Account.new
account.find_by_id(account_id,
                   with_balance, 
                   with_balance_and_cba,
                   options)

accountApi = killbill.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.get_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "name": "John Doe",
  "firstNameLength": null,
  "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "email": "john@laposte.com",
  "billCycleDayLocal": 0,
  "currency": "USD",
  "parentAccountId": null,
  "isPaymentDelegatedToParent": false,
  "paymentMethodId": null,
  "referenceTime": "2018-07-17T15:02:45.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": []
}

class Account {
    org.killbill.billing.client.model.gen.Account@4be0cf3a
    accountId: 864c1418-e768-4cd5-a0db-67537144b685
    name: John Doe
    firstNameLength: null
    externalKey: 864c1418-e768-4cd5-a0db-67537144b685
    email: john@laposte.com
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: null
    isPaymentDelegatedToParent: false
    paymentMethodId: null
    referenceTime: 2012-08-25T00:00:25.000Z
    timeZone: UTC
    address1: null
    address2: null
    postalCode: null
    company: null
    city: null
    state: null
    country: null
    locale: null
    phone: null
    notes: null
    isMigrated: false
    accountBalance: null
    accountCBA: null
    auditLogs: []
}

{
   "accountId":"e8877928-0226-488d-9272-07a5e66d897f",
   "name":"John Doe",
   "firstNameLength":null,
   "externalKey":"e8877928-0226-488d-9272-07a5e66d897f",
   "email":"john@laposte.com",
   "billCycleDayLocal":0,
   "currency":"USD",
   "parentAccountId":null,
   "isPaymentDelegatedToParent":false,
   "paymentMethodId":null,
   "referenceTime":"2018-02-05T22:39:53.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":[]
}

{
 'account_balance': None,
 'account_cba': None,
 'account_id': '07c0cef4-41c5-4606-b2cd-661332cdd41c',
 'address1': None,
 'address2': None,
 'audit_logs': [],
 'bill_cycle_day_local': 0,
 'city': None,
 'company': None,
 'country': 'USA',
 'currency': 'USD',
 'email': None,
 'external_key': 'rpwtgr',
 'first_name_length': None,
 'is_migrated': False,
 'is_notified_for_invoices': False,
 'is_payment_delegated_to_parent': False,
 'locale': None,
 'name': 'John',
 'notes': None,
 'parent_account_id': None,
 'payment_method_id': None,
 'phone': None,
 'postal_code': None,
 'reference_time': datetime.datetime(2018, 5, 3, 15, 53, 44, tzinfo=tzutc()),
 'state': 'CA',
 'time_zone': 'UTC'
}

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=2ad52f53-85ae-408a-9879-32a7e59dd03d"

import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

String externalKey = "example_external_key";
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 = 'example_external_key'
with_balance = false
with_balance_and_cba = false

account = KillBillClient::Model::Account.new
account.find_by_external_key(external_key,
                             with_balance,
                             with_balance_and_cba, 
                             options)

accountApi = killbill.api.AccountApi()
external_key = 'example_external_key'

accountApi.get_account(external_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "name": "John Doe",
  "firstNameLength": null,
  "externalKey": "example_external_key",
  "email": "john@laposte.com",
  "billCycleDayLocal": 0,
  "currency": "USD",
  "parentAccountId": null,
  "isPaymentDelegatedToParent": false,
  "paymentMethodId": null,
  "referenceTime": "2018-07-17T15:02:45.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": []
}

class Account {
    org.killbill.billing.client.model.gen.Account@4be0cf3a
    accountId: 864c1418-e768-4cd5-a0db-67537144b685
    name: John Doe
    firstNameLength: null
    externalKey: example_external_key
    email: john@laposte.com
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: null
    isPaymentDelegatedToParent: false
    paymentMethodId: null
    referenceTime: 2012-08-25T00:00:25.000Z
    timeZone: UTC
    address1: null
    address2: null
    postalCode: null
    company: null
    city: null
    state: null
    country: null
    locale: null
    phone: null
    notes: null
    isMigrated: false
    accountBalance: null
    accountCBA: null
    auditLogs: []
}

{
   "accountId":"e8877928-0226-488d-9272-07a5e66d897f",
   "name":"John Doe",
   "firstNameLength":null,
   "externalKey":"example_external_key",
   "email":"john@laposte.com",
   "billCycleDayLocal":0,
   "currency":"USD",
   "parentAccountId":null,
   "isPaymentDelegatedToParent":false,
   "paymentMethodId":null,
   "referenceTime":"2018-02-05T22:39:53.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":[]
}

{
 'account_balance': None,
 'account_cba': None,
 'account_id': '07c0cef4-41c5-4606-b2cd-661332cdd41c',
 'address1': None,
 'address2': None,
 'audit_logs': [],
 'bill_cycle_day_local': 0,
 'city': None,
 'company': None,
 'country': 'USA',
 'currency': 'USD',
 'email': None,
 'external_key': 'example_external_key',
 'first_name_length': None,
 'is_migrated': False,
 'is_notified_for_invoices': False,
 'is_payment_delegated_to_parent': False,
 'locale': None,
 'name': 'John',
 'notes': None,
 'parent_account_id': None,
 'payment_method_id': None,
 'phone': None,
 'postal_code': None,
 'reference_time': datetime.datetime(2018, 5, 3, 15, 53, 44, tzinfo=tzutc()),
 'state': 'CA',
 'time_zone': 'UTC'
}

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.name = 'Another Name'
treat_null_as_reset = true

account.update(treat_null_as_reset,
               user,
               reason,
               comment, 
               options)

accountApi = killbill.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'
created_by = 'example'
body = Account(name='Another Name')

accountApi.update_account(account_id, 
                          body, 
                          created_by, 
                          api_key, 
                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

{
   "accountId":"37e759ed-e769-4e81-9e39-afb75a33056d",
   "name":"Another Name",
   "externalKey":"1521656367-130272",
   "email":"kill@bill.com",
   "billCycleDayLocal":0,
   "currency":"USD",
   "isPaymentDelegatedToParent":false,
   "timeZone":"UTC",
   "address1":"7, yoyo road",
   "address2":"Apt 5",
   "postalCode":"94105",
   "company":"Unemployed",
   "city":"San Francisco",
   "state":"California",
   "country":"US",
   "locale":"fr_FR",
   "notes":"My notes",
   "auditLogs":[]
}

no content

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

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.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.close_account(account_id,
                         created_by,
                         api_key,
                         api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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

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

account.find_in_batches(offset,
                        limit,
                        with_balance,
                        with_balance_and_cba,
                        options)

accountApi = killbill.api.AccountApi()

accountApi.get_accounts(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "name": "John Doe",
    "firstNameLength": null,
    "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "email": "john@laposte.com",
    "billCycleDayLocal": 0,
    "currency": "USD",
    "parentAccountId": null,
    "isPaymentDelegatedToParent": false,
    "paymentMethodId": null,
    "referenceTime": "2018-07-17T15:02:45.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": []
  }
]

// First element of the list
class Account {
    org.killbill.billing.client.model.gen.Account@f0247489
    accountId: 80e54c79-ca2b-4c82-920b-07822683e605
    name: 34bd86b6-ebc8-49ea-9a6e-6bbbd61ac745
    firstNameLength: 4
    externalKey: 23338712-3409-4ad3-8c6d-1c95241efef6
    email: f1a3a@44a80
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: null
    isPaymentDelegatedToParent: false
    paymentMethodId: null
    referenceTime: 2012-08-25T00:00:01.000Z
    timeZone: UTC
    address1: 12 rue des ecoles
    address2: Poitier
    postalCode: 44 567
    company: Renault
    city: Quelque part
    state: Poitou
    country: France
    locale: fr
    phone: 81 53 26 56
    notes: notes
    isMigrated: false
    accountBalance: null
    accountCBA: null
    auditLogs: []
}

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

[{'account_balance': None,
 'account_cba': None,
 'account_id': '224a9677-735b-4902-a4a4-bf77469a0846',
 'address1': None,
 'address2': None,
 'audit_logs': [],
 'bill_cycle_day_local': 0,
 'city': None,
 'company': None,
 'country': 'USA',
 'currency': 'USD',
 'email': None,
 'external_key': 'fxelpb',
 'first_name_length': None,
 'is_migrated': False,
 'is_notified_for_invoices': False,
 'is_payment_delegated_to_parent': False,
 'locale': None,
 'name': 'John-0',
 'notes': None,
 'parent_account_id': None,
 'payment_method_id': None,
 'phone': None,
 'postal_code': None,
 'reference_time': datetime.datetime(2018, 5, 4, 19, 40, 35, tzinfo=tzutc()),
 'state': 'CA',
 'time_zone': 'UTC'}, {'account_balance': None,
 'account_cba': None,
 'account_id': '465f0295-e27e-4341-9eb7-072465e32ee5',
 'address1': None,
 'address2': None,
 'audit_logs': [],
 'bill_cycle_day_local': 0,
 'city': None,
 'company': None,
 'country': 'USA',
 'currency': 'USD',
 'email': None,
 'external_key': 'cpkwdl',
 'first_name_length': None,
 'is_migrated': False,
 'is_notified_for_invoices': False,
 'is_payment_delegated_to_parent': False,
 'locale': None,
 'name': 'John-1',
 'notes': None,
 'parent_account_id': None,
 'payment_method_id': None,
 'phone': None,
 'postal_code': None,
 'reference_time': datetime.datetime(2018, 5, 4, 19, 40, 36, tzinfo=tzutc()),
 'state': 'CA',
 'time_zone': 'UTC'}]

Query Parameters

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

Response

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

Search accounts

Search for an account by a specified search string. The search string is compared to the following attributes: accountId, name, email, companyName, and externalKey. The operation returns all account records in which the search string matches all or part of any one of these attributes.

HTTP Request

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

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/search/John%20Doe"

import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

String searchKey = "John-1";
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);

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

account.find_in_batches_by_search_key(search_key,
                                      offset,
                                      limit,
                                      with_balance,
                                      with_balance_and_cba,
                                      options)

accountApi = killbill.api.AccountApi()
search_key = 'John-1'

accountApi.search_accounts(search_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "name": "John Doe",
    "firstNameLength": null,
    "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "email": "john@laposte.com",
    "billCycleDayLocal": 0,
    "currency": "USD",
    "parentAccountId": null,
    "isPaymentDelegatedToParent": false,
    "paymentMethodId": null,
    "referenceTime": "2018-07-17T15:02:45.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": []
  }
]

// First element of the list
class Account {
    org.killbill.billing.client.model.gen.Account@24e22684
    accountId: 80a454f3-182f-4621-812e-533d23e54cb9
    name: John-1
    firstNameLength: 4
    externalKey: 94a664a3-eea5-43fb-8788-9d3129a2c95c
    email: 33b2e@cc77b
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: null
    isPaymentDelegatedToParent: false
    paymentMethodId: null
    referenceTime: 2012-08-25T00:00:02.000Z
    timeZone: UTC
    address1: 12 rue des ecoles
    address2: Poitier
    postalCode: 44 567
    company: Renault
    city: Quelque part
    state: Poitou
    country: France
    locale: fr
    phone: 81 53 26 56
    notes: notes
    isMigrated: false
    accountBalance: null
    accountCBA: null
    auditLogs: []
}

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

[{'account_balance': None,
 'account_cba': None,
 'account_id': 'c41bf53b-c6a8-48de-8012-b755e51d5d3e',
 'address1': None,
 'address2': None,
 'audit_logs': [],
 'bill_cycle_day_local': 0,
 'city': None,
 'company': None,
 'country': 'USA',
 'currency': 'USD',
 'email': None,
 'external_key': 'njisdn',
 'first_name_length': None,
 'is_migrated': False,
 'is_notified_for_invoices': False,
 'is_payment_delegated_to_parent': False,
 'locale': None,
 'name': 'John-1',
 'notes': None,
 'parent_account_id': None,
 'payment_method_id': None,
 'phone': None,
 'postal_code': None,
 'reference_time': datetime.datetime(2018, 5, 4, 19, 44, 24, tzinfo=tzutc()),
 'state': 'CA',
 'time_zone': 'UTC'}]

Query Parameters

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

Response

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

Email

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

Add account email

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

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "email": "email@laposte.com"}' \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails"

import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

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

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

accountApi.addEmail(accountId,
                    accountEmail,
                    requestOptions);

account.email = 'email@laposte.com'

account.add_email(account.email,
                  user,
                  reason,
                  comment,
                  options)

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

accountApi.add_email(account_id,
                     body,
                     created_by,
                     api_key,
                     api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

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

audit = 'NONE'
account.emails(audit, options)

accountApi = killbill.api.AccountApi()
account_id = 'c8f51346-562d-429b-8c89-27a0f72009b3'

accountApi.get_emails(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class AccountEmail {
    org.killbill.billing.client.model.gen.AccountEmail@bdc0f8ad
    accountId: cd026587-c93b-471c-a98d-224c21636fbc
    email: email@laposte.com
    auditLogs: []
}

[
   {
      "accountId":"2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "email":"email@laposte.com"
   }
]

[
  {
    'account_id': 'c8f51346-562d-429b-8c89-27a0f72009b3',
    'audit_logs': [],
    'email': 'email@laposte.com'
  }
]

Query Parameters

None.

Response Body

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

Delete email

Deletes an email from an account

HTTP Request

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/emails/email@laposte.com"

import org.killbill.billing.client.api.gen.AccountApi;
protected AccountApi accountApi;

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

accountApi.removeEmail(accountId, 
                       email, 
                       requestOptions);

email = 'email@laposte.com'

account.remove_email(email,
                     user,
                     reason,
                     comment,
                     options)

accountApi = killbill.api.AccountApi()
account_id = 'c84de569-b654-4f7f-ab13-17616302d310'
email = 'email@laposte.com'

accountApi.remove_email(account_id,
                        email,
                        created_by,
                        api_key,
                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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.bundles(options)

accountApi = killbill.api.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountApi.get_account_bundles(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Bundle {
    org.killbill.billing.client.model.gen.Bundle@53060d66
    accountId: 15434b45-54c1-4a44-851c-b1f2f7a52f03
    bundleId: e17a7805-42cf-4464-aea7-963cf0078651
    externalKey: 123467
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@e1d5debf
        accountId: 15434b45-54c1-4a44-851c-b1f2f7a52f03
        bundleId: e17a7805-42cf-4464-aea7-963cf0078651
        subscriptionId: 7b9de82a-319c-4334-b676-f1644591077e
        externalKey: 123467
        startDate: 2012-08-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-08-25
        billingStartDate: 2012-08-25
        billingEndDate: null
        billCycleDayLocal: 24
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@6ea5e183
            eventId: a6e0c854-16b7-4729-bc6c-cb019b3441ce
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@3635a9d5
            eventId: 2cb255be-0008-44b0-9161-47760a5e2828
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a561e242
            eventId: a34e0990-80bb-42e1-a593-0a0bc952ef2c
            billingPeriod: MONTHLY
            effectiveDate: 2012-09-24
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: [class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePriceOverrides: []
        }, class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePriceOverrides: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@e70542
        accountId: 15434b45-54c1-4a44-851c-b1f2f7a52f03
        bundleId: e17a7805-42cf-4464-aea7-963cf0078651
        externalKey: 123467
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@1852601c
            eventId: a6e0c854-16b7-4729-bc6c-cb019b3441ce
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@1d0ca762
            eventId: 2cb255be-0008-44b0-9161-47760a5e2828
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a8ba9854
            eventId: a34e0990-80bb-42e1-a593-0a0bc952ef2c
            billingPeriod: MONTHLY
            effectiveDate: 2012-09-24
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

[
   {
      "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
      "bundleId":"a5221798-699a-48ac-a2d1-962839fd8fc9",
      "externalKey":"3-6138e5ee-2763-4729-829b-e7de038b46d0-889153",
      "subscriptions":[
         {
            "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
            "bundleId":"a5221798-699a-48ac-a2d1-962839fd8fc9",
            "subscriptionId":"937ff1a8-2290-4bb5-9166-7b7bb99cbccf",
            "externalKey":"3-6138e5ee-2763-4729-829b-e7de038b46d0-889153",
            "startDate":"2013-08-01",
            "productName":"Super",
            "productCategory":"BASE",
            "billingPeriod":"MONTHLY",
            "phaseType":"TRIAL",
            "priceList":"DEFAULT",
            "planName":"super-monthly",
            "state":"ACTIVE",
            "sourceType":"NATIVE",
            "chargedThroughDate":"2013-08-01",
            "billingStartDate":"2013-08-01",
            "billCycleDayLocal":31,
            "events":[
               {
                  "eventId":"c5ba5861-d4e4-46de-9ac5-d72ddf086ff2",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"super-monthly",
                  "product":"Super",
                  "priceList":"DEFAULT",
                  "eventType":"START_ENTITLEMENT",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement-service",
                  "serviceStateName":"ENT_STARTED",
                  "phase":"super-monthly-trial",
                  "auditLogs":[]
               },
               {
                  "eventId":"2add66b9-cd9f-47c3-906a-899aad32a350",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"super-monthly",
                  "product":"Super",
                  "priceList":"DEFAULT",
                  "eventType":"START_BILLING",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"billing-service",
                  "serviceStateName":"START_BILLING",
                  "phase":"super-monthly-trial",
                  "auditLogs":[]
               },
               {
                  "eventId":"86be39b0-0a70-4e15-a891-ed20aed6c12d",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-31",
                  "plan":"super-monthly",
                  "product":"Super",
                  "priceList":"DEFAULT",
                  "eventType":"PHASE",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement+billing-service",
                  "serviceStateName":"PHASE",
                  "phase":"super-monthly-evergreen",
                  "auditLogs":[]
               }
            ],
            "priceOverrides":[
               {
                  "planName":"super-monthly",
                  "phaseName":"super-monthly-trial",
                  "phaseType":"TRIAL",
                  "fixedPrice":0
               },
               {
                  "planName":"super-monthly",
                  "phaseName":"super-monthly-evergreen",
                  "phaseType":"EVERGREEN",
                  "recurringPrice":1000.0
               }
            ],
            "auditLogs":[]
         },
         {
            "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
            "bundleId":"a5221798-699a-48ac-a2d1-962839fd8fc9",
            "subscriptionId":"cf1c90f9-928c-43c1-9b88-633a0ac6d7f2",
            "externalKey":"3-6138e5ee-2763-4729-829b-e7de038b46d0-889153",
            "startDate":"2013-08-01",
            "productName":"Gas",
            "productCategory":"ADD_ON",
            "billingPeriod":"NO_BILLING_PERIOD",
            "phaseType":"EVERGREEN",
            "priceList":"DEFAULT",
            "planName":"gas-monthly",
            "state":"ACTIVE",
            "sourceType":"NATIVE",
            "billingStartDate":"2013-08-01",
            "billCycleDayLocal":31,
            "events":[
               {
                  "eventId":"08ec39ef-e9f5-4e58-957d-650d174938ab",
                  "billingPeriod":"NO_BILLING_PERIOD",
                  "effectiveDate":"2013-08-01",
                  "plan":"gas-monthly",
                  "product":"Gas",
                  "priceList":"DEFAULT",
                  "eventType":"START_ENTITLEMENT",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement-service",
                  "serviceStateName":"ENT_STARTED",
                  "phase":"gas-monthly-evergreen",
                  "auditLogs":[]
               },
               {
                  "eventId":"729268e7-583b-49f2-be84-477ae444c363",
                  "billingPeriod":"NO_BILLING_PERIOD",
                  "effectiveDate":"2013-08-01",
                  "plan":"gas-monthly",
                  "product":"Gas",
                  "priceList":"DEFAULT",
                  "eventType":"START_BILLING",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"billing-service",
                  "serviceStateName":"START_BILLING",
                  "phase":"gas-monthly-evergreen",
                  "auditLogs":[]
               }
            ],
            "priceOverrides":[
               {
                  "planName":"gas-monthly",
                  "phaseName":"gas-monthly-evergreen",
                  "phaseType":"EVERGREEN"
               }
            ],
            "auditLogs":[]
         }
      ],
      "timeline":{
         "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
         "bundleId":"a5221798-699a-48ac-a2d1-962839fd8fc9",
         "externalKey":"3-6138e5ee-2763-4729-829b-e7de038b46d0-889153",
         "events":[
            {
               "eventId":"08ec39ef-e9f5-4e58-957d-650d174938ab",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"super-monthly",
               "product":"Super",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"super-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"c5ba5861-d4e4-46de-9ac5-d72ddf086ff2",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"super-monthly",
               "product":"Super",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"super-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"2add66b9-cd9f-47c3-906a-899aad32a350",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"super-monthly",
               "product":"Super",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"super-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"729268e7-583b-49f2-be84-477ae444c363",
               "billingPeriod":"NO_BILLING_PERIOD",
               "effectiveDate":"2013-08-01",
               "plan":"gas-monthly",
               "product":"Gas",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"gas-monthly-evergreen",
               "auditLogs":[]
            },
            {
               "eventId":"86be39b0-0a70-4e15-a891-ed20aed6c12d",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-31",
               "plan":"super-monthly",
               "product":"Super",
               "priceList":"DEFAULT",
               "eventType":"PHASE",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement+billing-service",
               "serviceStateName":"PHASE",
               "phase":"super-monthly-evergreen",
               "auditLogs":[]
            }
         ],
         "auditLogs":[]
      },
      "auditLogs":[]
   },
   {
      "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
      "bundleId":"e71f6dc2-ece9-4d31-8cea-81472784ded3",
      "externalKey":"2-6138e5ee-2763-4729-829b-e7de038b46d0-979751",
      "subscriptions":[
         {
            "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
            "bundleId":"e71f6dc2-ece9-4d31-8cea-81472784ded3",
            "subscriptionId":"2be86a1f-0516-4fda-a094-7467f2171d7f",
            "externalKey":"2-6138e5ee-2763-4729-829b-e7de038b46d0-979751",
            "startDate":"2013-08-01",
            "productName":"Standard",
            "productCategory":"BASE",
            "billingPeriod":"MONTHLY",
            "phaseType":"TRIAL",
            "priceList":"DEFAULT",
            "planName":"standard-monthly",
            "state":"ACTIVE",
            "sourceType":"NATIVE",
            "chargedThroughDate":"2013-08-01",
            "billingStartDate":"2013-08-01",
            "billCycleDayLocal":31,
            "events":[
               {
                  "eventId":"4e9cff06-c558-48b0-adad-6dda59ac551c",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "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":"2d32bd25-46d6-448e-a5ca-f07c56dd2feb",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "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":"d7754b8e-cc06-4bb7-afbf-022860261f14",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-31",
                  "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":[
               {
                  "planName":"standard-monthly",
                  "phaseName":"standard-monthly-trial",
                  "phaseType":"TRIAL",
                  "fixedPrice":0
               },
               {
                  "planName":"standard-monthly",
                  "phaseName":"standard-monthly-evergreen",
                  "phaseType":"EVERGREEN",
                  "recurringPrice":100.0
               }
            ],
            "auditLogs":[]
         }
      ],
      "timeline":{
         "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
         "bundleId":"e71f6dc2-ece9-4d31-8cea-81472784ded3",
         "externalKey":"2-6138e5ee-2763-4729-829b-e7de038b46d0-979751",
         "events":[
            {
               "eventId":"4e9cff06-c558-48b0-adad-6dda59ac551c",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "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":"2d32bd25-46d6-448e-a5ca-f07c56dd2feb",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "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":"d7754b8e-cc06-4bb7-afbf-022860261f14",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-31",
               "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":[]
   },
   {
      "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
      "bundleId":"3c7d6f02-bd9b-4f23-8a44-d806d3cbe330",
      "externalKey":"1-6138e5ee-2763-4729-829b-e7de038b46d0-909112",
      "subscriptions":[
         {
            "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
            "bundleId":"3c7d6f02-bd9b-4f23-8a44-d806d3cbe330",
            "subscriptionId":"d64a410b-49b6-47af-88a3-cbd203289246",
            "externalKey":"1-6138e5ee-2763-4729-829b-e7de038b46d0-909112",
            "startDate":"2013-08-01",
            "productName":"Sports",
            "productCategory":"BASE",
            "billingPeriod":"MONTHLY",
            "phaseType":"TRIAL",
            "priceList":"DEFAULT",
            "planName":"sports-monthly",
            "state":"ACTIVE",
            "sourceType":"NATIVE",
            "chargedThroughDate":"2013-08-01",
            "billingStartDate":"2013-08-01",
            "billCycleDayLocal":31,
            "events":[
               {
                  "eventId":"ae420517-05d4-4a5d-bbe9-0f81a433efd3",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"sports-monthly",
                  "product":"Sports",
                  "priceList":"DEFAULT",
                  "eventType":"START_ENTITLEMENT",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement-service",
                  "serviceStateName":"ENT_STARTED",
                  "phase":"sports-monthly-trial",
                  "auditLogs":[]
               },
               {
                  "eventId":"d2179af5-1deb-4e2a-a934-9bad8cac04bd",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"sports-monthly",
                  "product":"Sports",
                  "priceList":"DEFAULT",
                  "eventType":"START_BILLING",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"billing-service",
                  "serviceStateName":"START_BILLING",
                  "phase":"sports-monthly-trial",
                  "auditLogs":[]
               },
               {
                  "eventId":"d45754a1-eb41-4a87-9714-80e2975a9f9a",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-31",
                  "plan":"sports-monthly",
                  "product":"Sports",
                  "priceList":"DEFAULT",
                  "eventType":"PHASE",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement+billing-service",
                  "serviceStateName":"PHASE",
                  "phase":"sports-monthly-evergreen",
                  "auditLogs":[]
               }
            ],
            "priceOverrides":[
               {
                  "planName":"sports-monthly",
                  "phaseName":"sports-monthly-trial",
                  "phaseType":"TRIAL",
                  "fixedPrice":0
               },
               {
                  "planName":"sports-monthly",
                  "phaseName":"sports-monthly-evergreen",
                  "phaseType":"EVERGREEN",
                  "recurringPrice":500.0
               }
            ],
            "auditLogs":[]
         },
         {
            "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
            "bundleId":"3c7d6f02-bd9b-4f23-8a44-d806d3cbe330",
            "subscriptionId":"b313e0f1-0c2e-4be7-bb6a-b4c8aff36341",
            "externalKey":"1-6138e5ee-2763-4729-829b-e7de038b46d0-909112",
            "startDate":"2013-08-01",
            "productName":"OilSlick",
            "productCategory":"ADD_ON",
            "billingPeriod":"MONTHLY",
            "phaseType":"DISCOUNT",
            "priceList":"DEFAULT",
            "planName":"oilslick-monthly",
            "state":"ACTIVE",
            "sourceType":"NATIVE",
            "chargedThroughDate":"2013-08-31",
            "billingStartDate":"2013-08-01",
            "billCycleDayLocal":31,
            "events":[
               {
                  "eventId":"1f06a132-d7e7-4fb6-ad96-8ef0a55ec38b",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"oilslick-monthly",
                  "product":"OilSlick",
                  "priceList":"DEFAULT",
                  "eventType":"START_ENTITLEMENT",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement-service",
                  "serviceStateName":"ENT_STARTED",
                  "phase":"oilslick-monthly-discount",
                  "auditLogs":[]
               },
               {
                  "eventId":"d783e243-2aa9-4463-a81b-030772d7945c",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"oilslick-monthly",
                  "product":"OilSlick",
                  "priceList":"DEFAULT",
                  "eventType":"START_BILLING",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"billing-service",
                  "serviceStateName":"START_BILLING",
                  "phase":"oilslick-monthly-discount",
                  "auditLogs":[]
               },
               {
                  "eventId":"267a056b-85b9-4912-8231-597e9905519c",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-09-01",
                  "plan":"oilslick-monthly",
                  "product":"OilSlick",
                  "priceList":"DEFAULT",
                  "eventType":"PHASE",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement+billing-service",
                  "serviceStateName":"PHASE",
                  "phase":"oilslick-monthly-evergreen",
                  "auditLogs":[]
               }
            ],
            "priceOverrides":[
               {
                  "planName":"oilslick-monthly",
                  "phaseName":"oilslick-monthly-discount",
                  "phaseType":"DISCOUNT",
                  "recurringPrice":4.0
               },
               {
                  "planName":"oilslick-monthly",
                  "phaseName":"oilslick-monthly-evergreen",
                  "phaseType":"EVERGREEN",
                  "recurringPrice":7.95
               }
            ],
            "auditLogs":[]
         }
      ],
      "timeline":{
         "accountId":"6138e5ee-2763-4729-829b-e7de038b46d0",
         "bundleId":"3c7d6f02-bd9b-4f23-8a44-d806d3cbe330",
         "externalKey":"1-6138e5ee-2763-4729-829b-e7de038b46d0-909112",
         "events":[
            {
               "eventId":"1f06a132-d7e7-4fb6-ad96-8ef0a55ec38b",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"oilslick-monthly",
               "product":"OilSlick",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"oilslick-monthly-discount",
               "auditLogs":[]
            },
            {
               "eventId":"ae420517-05d4-4a5d-bbe9-0f81a433efd3",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"oilslick-monthly",
               "product":"OilSlick",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"oilslick-monthly-discount",
               "auditLogs":[]
            },
            {
               "eventId":"d783e243-2aa9-4463-a81b-030772d7945c",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"oilslick-monthly",
               "product":"OilSlick",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"oilslick-monthly-discount",
               "auditLogs":[]
            },
            {
               "eventId":"d2179af5-1deb-4e2a-a934-9bad8cac04bd",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"sports-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"d45754a1-eb41-4a87-9714-80e2975a9f9a",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-31",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"PHASE",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement+billing-service",
               "serviceStateName":"PHASE",
               "phase":"sports-monthly-evergreen",
               "auditLogs":[]
            },
            {
               "eventId":"267a056b-85b9-4912-8231-597e9905519c",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-09-01",
               "plan":"oilslick-monthly",
               "product":"OilSlick",
               "priceList":"DEFAULT",
               "eventType":"PHASE",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement+billing-service",
               "serviceStateName":"PHASE",
               "phase":"oilslick-monthly-evergreen",
               "auditLogs":[]
            }
         ],
         "auditLogs":[]
      },
      "auditLogs":[]
   }
]

[{'account_id': '8992e146-bfa1-4126-a045-98b844a4adcb',
 'audit_logs': [],
 'bundle_id': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc',
 'external_key': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc',
 'subscriptions': [{'account_id': '8992e146-bfa1-4126-a045-98b844a4adcb',
                    'audit_logs': [],
                    'bill_cycle_day_local': 2,
                    'billing_end_date': None,
                    'billing_period': 'MONTHLY',
                    'billing_start_date': datetime.date(2018, 5, 3),
                    'bundle_id': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc',
                    'cancelled_date': None,
                    'charged_through_date': None,
                    'events': [{'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 3),
                                'event_id': 'efa8c4ae-a514-4950-b6f5-58f1e1d17846',
                                'event_type': 'START_ENTITLEMENT',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement-service',
                                'service_state_name': 'ENT_STARTED'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 3),
                                'event_id': '94470035-33c0-42bc-a041-58aa13bdae93',
                                'event_type': 'START_BILLING',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'billing-service',
                                'service_state_name': 'START_BILLING'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 6, 2),
                                'event_id': '9d369364-1a5d-4291-9ecd-4cb0617ef5b3',
                                'event_type': 'PHASE',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-evergreen',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement+billing-service',
                                'service_state_name': 'PHASE'}],
                    'external_key': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc',
                    'phase_type': 'TRIAL',
                    'plan_name': 'standard-monthly',
                    'price_list': 'DEFAULT',
                    'price_overrides': [{'fixed_price': 0.0,
                                         'phase_name': 'standard-monthly-trial',
                                         'phase_type': 'TRIAL',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': None,
                                         'usage_price_overrides': []},
                                        {'fixed_price': None,
                                         'phase_name': 'standard-monthly-evergreen',
                                         'phase_type': 'EVERGREEN',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': 100.0,
                                         'usage_price_overrides': []}],
                    'product_category': 'BASE',
                    'product_name': 'Standard',
                    'source_type': 'NATIVE',
                    'start_date': datetime.date(2018, 5, 3),
                    'state': 'ACTIVE',
                    'subscription_id': 'a0f6dcd9-4dbc-43d2-876a-9dcc7dfb7d3b'}],
 'timeline': {'account_id': '8992e146-bfa1-4126-a045-98b844a4adcb',
              'audit_logs': [],
              'bundle_id': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc',
              'events': [{'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 3),
                          'event_id': 'efa8c4ae-a514-4950-b6f5-58f1e1d17846',
                          'event_type': 'START_ENTITLEMENT',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement-service',
                          'service_state_name': 'ENT_STARTED'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 3),
                          'event_id': '94470035-33c0-42bc-a041-58aa13bdae93',
                          'event_type': 'START_BILLING',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'billing-service',
                          'service_state_name': 'START_BILLING'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 6, 2),
                          'event_id': '9d369364-1a5d-4291-9ecd-4cb0617ef5b3',
                          'event_type': 'PHASE',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-evergreen',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement+billing-service',
                          'service_state_name': 'PHASE'}],
              'external_key': 'd636e7e9-e1e3-43ff-94a6-01a868b064cc'}}]

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.

Invoice

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

Retrieve account invoices

List the Invoices associated with this account.

HTTP Request

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

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

Invoices invoices = accountApi.getInvoicesForAccount(accountId,
                                                     startDate, 
                                                     endDate,
                                                     withMigrationInvoices, 
                                                     unpaidInvoicesOnly, 
                                                     includeVoidedInvoices, 
                                                     AuditLevel.FULL, 
                                                     requestOptions);

account.invoices(with_items,
                 options)

accountApi = killbill.api.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountApi.get_invoices_for_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Invoice {
    org.killbill.billing.client.model.gen.Invoice@df84aad8
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 66448454-4ff2-4a4c-9817-167c062fcde9
    invoiceDate: 2012-04-25
    targetDate: 2012-04-25
    invoiceNumber: 1
    balance: 0.00
    accountId: d3a82897-ae72-4a2e-9bca-e3c1fe087f84
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@7e405309
        invoiceItemId: 898d4b59-9e85-48cc-b05e-33d2059b6250
        invoiceId: 66448454-4ff2-4a4c-9817-167c062fcde9
        linkedInvoiceItemId: null
        accountId: d3a82897-ae72-4a2e-9bca-e3c1fe087f84
        childAccountId: null
        bundleId: 823db38d-864f-4123-96e1-86218663e1bd
        subscriptionId: 8c0b5800-c892-4898-9295-837ecadad2f0
        productName: Shotgun
        planName: shotgun-monthly
        phaseName: shotgun-monthly-trial
        usageName: null
        prettyProductName: Shotgun
        prettyPlanName: Shotgun Monthly
        prettyPhaseName: shotgun-monthly-trial
        prettyUsageName: null
        itemType: FIXED
        description: shotgun-monthly-trial
        startDate: 2012-04-25
        endDate: null
        amount: 0.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        childItems: null
        auditLogs: [class AuditLog {
            changeType: INSERT
            changeDate: 2012-04-25T00:03:43.000Z
            objectType: INVOICE_ITEM
            objectId: 898d4b59-9e85-48cc-b05e-33d2059b6250
            changedBy: SubscriptionBaseTransition
            reasonCode: null
            comments: null
            userToken: fc3e7a8d-7e8c-4b9d-a6ac-557cd2e74ccd
            history: null
        }]
    }]
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-04-25T00:03:43.000Z
        objectType: INVOICE
        objectId: 66448454-4ff2-4a4c-9817-167c062fcde9
        changedBy: SubscriptionBaseTransition
        reasonCode: null
        comments: null
        userToken: fc3e7a8d-7e8c-4b9d-a6ac-557cd2e74ccd
        history: null
    }]
}

[
   {
      "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":"1f310060-dad6-4151-87af-c58a4fe87679",
      "items":[
         {
            "invoiceItemId":"5f3b4e9c-66bd-4c5c-b84a-4ae951cc2f1d",
            "invoiceId":"d981abbb-3622-487a-9564-d594c9d04f83",
            "accountId":"1f310060-dad6-4151-87af-c58a4fe87679",
            "itemType":"EXTERNAL_CHARGE",
            "description":"Some description",
            "startDate":"2013-08-01",
            "amount":50.0,
            "currency":"USD",
            "auditLogs":[]
         }
      ],
      "isParentInvoice":false,
      "auditLogs":[]
   }
]

[{'account_id': '82ecbf80-ddd2-4208-92be-2d3b2b7fc266',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 4),
 'invoice_id': 'da4a1c85-c18c-4d88-8005-e3c4039c218b',
 'invoice_number': '764',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 4)}, {'account_id': '82ecbf80-ddd2-4208-92be-2d3b2b7fc266',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 4),
 'invoice_id': '00b24709-160b-4472-8741-e0f271a67fe0',
 'invoice_number': '765',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 4)}, {'account_id': '82ecbf80-ddd2-4208-92be-2d3b2b7fc266',
 'amount': 50.0,
 'audit_logs': [],
 'balance': 50.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 4),
 'invoice_id': '6e2be596-f6f0-4453-9551-3638af9088d2',
 'invoice_number': '766',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 4)}]

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

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;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.payAllInvoices(accountId, 
                          paymentMethodId, 
                          externalPayment, 
                          paymentAmount, 
                          targetDate,
                          NULL_PLUGIN_PROPERTIES, 
                          requestOptions);

invoice_payment                  = KillBillClient::Model::InvoicePayment.new
invoice_payment.account_id       = account.account_id
invoice_payment.purchased_amount = '50.0'

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.api.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountApi.pay_all_invoices(account_id, 
                            created_by,
                            api_key, 
                            api_secret, 
                            external_payment=True,
                            payment_method_id=None,
                            target_date=None)

Example Response:

# Subset of headers returned when specifying -v curl option
< 201
< Content-Type: application/json
< Location: http://127.0.0.1:8080/1.0/kb/accounts/82ecbf80-ddd2-4208-92be-2d3b2b7fc266/invoices?endDate=2012-05-25&invoicesFilter=c6ca1d31-4e22-4011-ba38-058df9369536&startDate=2012-05-25

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@f31161b5
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: ee0fc684-09af-4b50-a7b2-85bd0e99e3d6
    invoiceDate: 2012-04-25
    targetDate: 2012-04-25
    invoiceNumber: 1
    balance: 0.00
    accountId: 82ecbf80-ddd2-4208-92be-2d3b2b7fc266/
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@f8d70905
        invoiceItemId: 0a446486-77ca-4948-8631-c696fa0b6b4f
        invoiceId: ee0fc684-09af-4b50-a7b2-85bd0e99e3d6
        linkedInvoiceItemId: null
        accountId: 82ecbf80-ddd2-4208-92be-2d3b2b7fc266/
        childAccountId: null
        bundleId: 38f03432-82be-4536-93df-2619e156afcd
        subscriptionId: 5f0f5def-d2b0-42df-80fc-156806a62f3e
        productName: Shotgun
        planName: shotgun-monthly
        phaseName: shotgun-monthly-trial
        usageName: null
        prettyProductName: Shotgun
        prettyPlanName: Shotgun Monthly
        prettyPhaseName: shotgun-monthly-trial
        prettyUsageName: null
        itemType: FIXED
        description: shotgun-monthly-trial
        startDate: 2012-04-25
        endDate: null
        amount: 0.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        catalogEffectiveDate: 2011-01-01T00:00:00.000Z
        childItems: null
        auditLogs: []
    }]
    trackingIds: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

no content

no content

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");
ImmutableMap<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.invoice_payments(audit,
                         with_plugin_info,
                         with_attempts,
                         options)

accountApi = killbill.api.AccountApi()
account_id = '110952d7-1b7e-482c-b6bb-103e46794927'

accountApi.get_invoice_payments(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@40d72f3f
    targetInvoiceId: a84bb73f-bafc-48cc-880f-3b2fa7d80d58
    accountId: e011caa5-ba35-4ac6-81cb-63b4f08122dc
    paymentId: 66d4954d-f8f3-4611-903e-371a6e6d076c
    paymentNumber: 1
    paymentExternalKey: 66d4954d-f8f3-4611-903e-371a6e6d076c
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 249.95
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 9934bcc5-3ea5-4eb9-85fb-bef74225e1de
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@5ad9bcb6
        transactionId: 5a7b1d87-98a1-4cbb-8967-f53733d032be
        transactionExternalKey: 5a7b1d87-98a1-4cbb-8967-f53733d032be
        paymentId: 66d4954d-f8f3-4611-903e-371a6e6d076c
        paymentExternalKey: 66d4954d-f8f3-4611-903e-371a6e6d076c
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:04.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

[
   {
      "targetInvoiceId":"d1d6e8d8-c476-4b53-badf-c23f78c02c09",
      "accountId":"e967f6ac-e713-4bbd-aa7e-473e6d35674c",
      "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":[]
   }
]

[{'account_id': '110952d7-1b7e-482c-b6bb-103e46794927',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '00ac58a6-7f0e-4149-9682-7d2110a18fb7',
 'payment_id': '00ac58a6-7f0e-4149-9682-7d2110a18fb7',
 'payment_method_id': '4a2a793a-48b0-41f1-ab7e-eff4efda3747',
 'payment_number': '291',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'target_invoice_id': '9696fb14-6016-484d-b288-f57854d61193',
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 4, 16, 51, 1, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '00ac58a6-7f0e-4149-9682-7d2110a18fb7',
                   'payment_id': '00ac58a6-7f0e-4149-9682-7d2110a18fb7',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '1063f716-cf90-42fe-aa2c-888fa21cf4bb',
                   'transaction_id': '1063f716-cf90-42fe-aa2c-888fa21cf4bb',
                   'transaction_type': 'PURCHASE'}]}]

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
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = accountApi.getPaymentsForAccount(accountId,
                                                     withAttempts,
                                                     withPluginInfo,
                                                     NULL_PLUGIN_PROPERTIES, 
                                                     AuditLevel.NONE,
                                                     requestOptions);

account.payments(options)

accountApi = killbill.api.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'

accountApi.get_payments_for_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Payment {
    org.killbill.billing.client.model.gen.Payment@1445c8b6
    accountId: e0fe95af-7d59-4b70-8252-165e1840410c
    paymentId: aef920ce-6887-4a00-8d0a-52cd6120517a
    paymentNumber: 1
    paymentExternalKey: aef920ce-6887-4a00-8d0a-52cd6120517a
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 249.95
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 9782b80d-6a0d-4051-9d05-b3fcd81c19e7
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@40873e28
        transactionId: d04e8592-8638-4768-9ac0-87b62a3cd516
        transactionExternalKey: d04e8592-8638-4768-9ac0-87b62a3cd516
        paymentId: aef920ce-6887-4a00-8d0a-52cd6120517a
        paymentExternalKey: aef920ce-6887-4a00-8d0a-52cd6120517a
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:04.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

[
   {
      "accountId":"6577439c-b783-4c60-82b2-c23e7b46eb97",
      "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":[

      ]
   }
]

[{'account_id': 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': 'cf34a5e5-b933-4efd-8e6d-502e8ae6be81',
 'payment_id': 'cf34a5e5-b933-4efd-8e6d-502e8ae6be81',
 'payment_method_id': '58065d90-6fb1-40ff-bbcb-aa21b45c76c0',
 'payment_number': '294',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 4, 18, 1, 15, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': 'cf34a5e5-b933-4efd-8e6d-502e8ae6be81',
                   'payment_id': 'cf34a5e5-b933-4efd-8e6d-502e8ae6be81',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': 'd1d52998-dc41-4f03-93e9-7f9a59445bb7',
                   'transaction_id': 'd1d52998-dc41-4f03-93e9-7f9a59445bb7',
                   'transaction_type': 'PURCHASE'}]}]

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");
ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

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

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

payment_method_id = payment_method.payment_method_id
refresh_options = nil

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

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

# Credit
transaction.credit(account.account_id,
                   payment_method_id, 
                   user, 
                   reason, 
                   comment, 
                   options, 
                   refresh_options)

accountApi = killbill.api.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, 
                           created_by, 
                           api_key, 
                           api_secret, 
                           payment_method_id=payment_method_id)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/payments/7c01a554-7b39-42dc-959f-3111724733d0
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@6816b5c8
    accountId: f4087a76-9f8a-4893-abbf-c5bb69975d1b
    paymentId: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
    paymentNumber: 1
    paymentExternalKey: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
    authAmount: 1.00
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 1d55ed5f-deea-4109-98b0-beb13a242f7c
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@29ef3d69
        transactionId: 3d40bc43-72ef-4aa6-8b3c-c8f1225a0971
        transactionExternalKey: 3d40bc43-72ef-4aa6-8b3c-c8f1225a0971
        paymentId: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
        paymentExternalKey: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
        transactionType: AUTHORIZE
        amount: 1.00
        currency: USD
        effectiveDate: 2018-09-04T03:05:35.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"2ad4cae9-c44a-43f9-b3f8-2e3e4e097838",
   "paymentId":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
   "paymentNumber":"333",
   "paymentExternalKey":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
   "authAmount":50.0,
   "capturedAmount":0,
   "purchasedAmount":0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"132d59c0-8c28-4115-947d-f57d430bc458",
   "transactions":[
      {
         "transactionId":"e038a04e-5304-4570-ab89-b7f04e8f496c",
         "transactionExternalKey":"e038a04e-5304-4570-ab89-b7f04e8f496c",
         "paymentId":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
         "paymentExternalKey":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
         "transactionType":"AUTHORIZE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:01.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

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");
ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

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

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

payment_method_id = '132d59c0-8c28-4115-947d-f57d430bc458'
refresh_options = nil

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

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

# Credit
transaction.credit_by_external_key(account.external_key,
                                   payment_method_id, 
                                   user, 
                                   reason, 
                                   comment, 
                                   options, 
                                   refresh_options)

accountApi = killbill.api.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,
                                           external_key,
                                           created_by,
                                           api_key,
                                           api_secret)
                                           payment_method_id=payment_method_id)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/payments/b4c5b34f-cd3e-4269-9f71-55daf8edde60
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@6816b5c8
    accountId: f4087a76-9f8a-4893-abbf-c5bb69975d1b
    paymentId: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
    paymentNumber: 1
    paymentExternalKey: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
    authAmount: 1.00
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 1d55ed5f-deea-4109-98b0-beb13a242f7c
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@29ef3d69
        transactionId: 3d40bc43-72ef-4aa6-8b3c-c8f1225a0971
        transactionExternalKey: 3d40bc43-72ef-4aa6-8b3c-c8f1225a0971
        paymentId: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
        paymentExternalKey: 0ecd1fdc-6c3e-4e06-b36f-9833f24ca607
        transactionType: AUTHORIZE
        amount: 1.00
        currency: USD
        effectiveDate: 2018-09-04T03:05:35.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"2ad4cae9-c44a-43f9-b3f8-2e3e4e097838",
   "paymentId":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
   "paymentNumber":"333",
   "paymentExternalKey":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
   "authAmount":50.0,
   "capturedAmount":0,
   "purchasedAmount":0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"132d59c0-8c28-4115-947d-f57d430bc458",
   "transactions":[
      {
         "transactionId":"e038a04e-5304-4570-ab89-b7f04e8f496c",
         "transactionExternalKey":"e038a04e-5304-4570-ab89-b7f04e8f496c",
         "paymentId":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
         "paymentExternalKey":"b4c5b34f-cd3e-4269-9f71-55daf8edde60",
         "transactionType":"AUTHORIZE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:01.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

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 '{ "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("d751dd57-7644-469a-9e69-f98d36d86f67");

UUID paymentMethodId = null;
String externalKey = UUID.randomUUID().toString();
Boolean isDefault = true; // Will set this new payment method as default
String pluginName = "__EXTERNAL_PAYMENT__"; 
PaymentMethodPluginDetail info = new PaymentMethodPluginDetail();
ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

PaymentMethod paymentMethod = new PaymentMethod(paymentMethodId, 
                                                externalKey, 
                                                accountId, 
                                                isDefault, 
                                                pluginName, 
                                                info, 
                                                EMPTY_AUDIT_LOGS);
ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentMethod paymentMethodPP = accountApi.createPaymentMethod(accountId, 
                                                               paymentMethod, 
                                                               NULL_PLUGIN_NAMES, 
                                                               NULL_PLUGIN_PROPERTIES, 
                                                               requestOptions);

pm             = KillBillClient::Model::PaymentMethod.new
pm.account_id  = account.account_id
pm.plugin_name = '__EXTERNAL_PAYMENT__'
pm.plugin_info = nil

is_default = true

pm.create(is_default, 
          user, 
          reason, 
          comment,
          options)

accountApi = killbill.api.AccountApi()
account_id = '059ecfb8-6b4d-4a89-9537-63a687e6cf10'
body = PaymentMethod(plugin_name='__EXTERNAL_PAYMENT__', plugin_info=None)

accountApi.create_payment_method(account_id, 
                                 body, 
                                 created_by, 
                                 api_key, 
                                 api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/paymentMethods/064cd61b-557d-48ba-8605-8d22912c7dfb
< Content-Type: application/json
< Content-Length: 0

class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@a820eeea
    paymentMethodId: 538c5a98-879b-4735-88df-e58f7a4bf874
    externalKey: a85a3fbe-30e8-457d-8a5a-55e16bcd730b
    accountId: d751dd57-7644-469a-9e69-f98d36d86f67
    isDefault: false
    pluginName: __EXTERNAL_PAYMENT__
    pluginInfo: null
    auditLogs: []
}

{
   "paymentMethodId":"059ecfb8-6b4d-4a89-9537-63a687e6cf10",
   "externalKey":"unknown",
   "accountId":"fa488b6e-c52a-450a-94bf-6607ae8b484f",
   "isDefault":true,
   "pluginName":"__EXTERNAL_PAYMENT__",
   "pluginInfo":{
      "properties":[]
   },
   "auditLogs":[]
}

no content

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");
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

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

account_id = account.account_id
with_plugin_info = false

payment_method.find_all_by_account_id(account_id, 
                                      with_plugin_info,
                                      options)

accountApi = killbill.api.AccountApi()
account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountApi.get_payment_methods_for_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@5528b1ed
    paymentMethodId: 1a4e5b9a-5280-4624-b2fc-2ea6d047d7fa
    externalKey: eed36074-d493-4335-839e-2adca4cb4187
    accountId: faf239a5-456a-4eb9-aef9-8d2254ef57dc
    isDefault: true
    pluginName: __EXTERNAL_PAYMENT__
    pluginInfo: null
    auditLogs: []
}

{
   "paymentMethodId":"059ecfb8-6b4d-4a89-9537-63a687e6cf10",
   "externalKey":"unknown",
   "accountId":"fa488b6e-c52a-450a-94bf-6607ae8b484f",
   "isDefault":true,
   "pluginName":"__EXTERNAL_PAYMENT__",
   "pluginInfo":{
      "properties":[]
   },
   "auditLogs":[]
}

[{'account_id': '88a5987a-1e1c-47c5-ba95-34ef14db3d46',
 'audit_logs': [],
 'external_key': 'unknown',
 'is_default': False,
 'payment_method_id': 'f49b513b-f045-46d8-9886-7f28df87e2a6',
 'plugin_info': None,
 'plugin_name': '__EXTERNAL_PAYMENT__'}]

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");
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.setDefaultPaymentMethod(accountId, 
                                   paymentMethodId, 
                                   NULL_PLUGIN_PROPERTIES, 
                                   requestOptions);

account_id = account.account_id
KillBillClient::Model::PaymentMethod.set_default(payment_method_id,
                                                 account_id,
                                                 user,
                                                 reason,
                                                 comment,
                                                 options)

accountApi = killbill.api.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, 
                                      api_key, 
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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__";
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

accountApi.refreshPaymentMethods(accountId, 
                                 pluginName, 
                                 NULL_PLUGIN_PROPERTIES, 
                                 requestOptions);

account_id = account.account_id

KillBillClient::Model::PaymentMethod.refresh(account_id, 
                                             user, 
                                             reason, 
                                             comment, 
                                             options)

accountApi = killbill.api.AccountApi()
account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountApi.refresh_payment_methods(account_id, 
                                   created_by,
                                   api_key,
                                   api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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.overdue(options)

accountApi = killbill.api.AccountApi()
account_id = '82ecbf80-ddd2-4208-92be-2d3b2b7fc266'

accountApi.get_overdue_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

class OverdueState {
    name: OD3
    externalMessage: Reached OD3
    daysBetweenPaymentRetries: [8, 8, 8]
    isDisableEntitlementAndChangesBlocked: true
    isBlockChanges: true
    isClearState: false
    reevaluationIntervalDays: 5
}

{
   "name":"__KILLBILL__CLEAR__OVERDUE_STATE__",
   "externalMessage":"",
   "daysBetweenPaymentRetries":[
      8,
      8,
      8
   ],
   "disableEntitlementAndChangesBlocked":false,
   "blockChanges":false,
   "clearState":true
}

{
 'days_between_payment_retries': [8, 8, 8],
 'external_message': '',
 'is_block_changes': False,
 'is_clear_state': True,
 'is_disable_entitlement_and_changes_blocked': False,
 'name': '__KILLBILL__CLEAR__OVERDUE_STATE__',
 'reevaluation_interval_days': None
}

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.

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 = ImmutableMap.<String, String>of();

BlockingStates result = accountApi.addAccountBlockingState(accountId,
                                                           blockingState,
                                                           requestedDate,
                                                           pluginProperty,
                                                           requestOptions);

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.api.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, 
                                      api_key, 
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/accounts/10483c3a-3394-4667-8519-0d849e9a8ec2/block?blockingStateTypes=ACCOUNT
< Content-Length: 0

[class BlockingState {
    org.killbill.billing.client.model.gen.BlockingState@be808444
    blockedId: 864c1418-e768-4cd5-a0db-67537144b685
    stateName: STATE1
    service: ServiceStateService
    isBlockChange: false
    isBlockEntitlement: false
    isBlockBilling: false
    effectiveDate: 2013-08-01T00:00:01.000Z
    type: ACCOUNT
    auditLogs: []
}]

no content

no content

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	Requested date to block an account
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 = ImmutableList.<BlockingStateType>of(BlockingStateType.SUBSCRIPTION_BUNDLE);
List<String> blockingStateSvcs = ImmutableList.<String>of("service");

BlockingStates blockingStates = accountApi.getBlockingStates(accountId, 
                                                             blockingStateTypes, 
                                                             blockingStateSvcs, 
                                                             AuditLevel.FULL, 
                                                             requestOptions);

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

account.blocking_states(blocking_state_types,
                        blocking_state_svcs, 
                        audit,
                        options)

accountApi = killbill.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.get_blocking_states(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class BlockingState {
    org.killbill.billing.client.model.gen.BlockingState@95047f38
    blockedId: e3d9aa57-1c1e-4206-a44a-d87e69d5bf2a
    stateName: block
    service: service
    isBlockChange: false
    isBlockEntitlement: true
    isBlockBilling: true
    effectiveDate: 2012-04-25T00:03:42.000Z
    type: SUBSCRIPTION_BUNDLE
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-04-25T00:03:45.000Z
        objectType: BLOCKING_STATES
        objectId: 8fc09849-bd98-417f-a0ab-943f9ce8e15d
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: 46d56616-1545-424a-882b-b158442534ff
        history: null
    }]
}

[
   {
      "blockedId":"d13b2272-d182-499c-a393-8efed203ae7d",
      "stateName":"STATE1",
      "service":"ServiceStateService",
      "blockChange":false,
      "blockEntitlement":false,
      "blockBilling":false,
      "effectiveDate":"2013-08-01T06:00:00.000Z",
      "type":"ACCOUNT",
      "auditLogs":[]
   }
]

[
  {
    'audit_logs': [],
    'blocked_id': '7e7dd5a9-6b65-4f40-a14b-1f4f408ef83c',
    'effective_date': datetime.datetime(2018, 5, 3, 19, 19, 12, tzinfo=tzutc()),
    'is_block_billing': False,
    'is_block_change': False,
    'is_block_entitlement': False,
    'service': 'ServiceStateService',
    'state_name': 'STATE1',
    'type': 'ACCOUNT'
  }
]

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_id = account.account_id
with_balance = false
with_balance_and_cba = false
audit = 'NONE'

childrens_account = KillBillClient::Model::Account.children(account_id,
                                                            with_balance, 
                                                            with_balance_and_cba, 
                                                            audit, 
                                                            options)

accountApi = killbill.api.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountApi.get_children_accounts(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Account {
    org.killbill.billing.client.model.gen.Account@cfbf4058
    accountId: b58e1b76-461c-4681-9ecf-3a3e5e95fc27
    name: 01f814b3-b4c2-41e9-9d6c-4a010916424c
    firstNameLength: 4
    externalKey: 3bf9144f-11a3-4a0b-9923-03a1c667ba93
    email: 8c0f9@f059d
    billCycleDayLocal: 0
    currency: USD
    parentAccountId: e72357f9-76ff-4533-b846-b61f39973b70
    isPaymentDelegatedToParent: true
    paymentMethodId: null
    referenceTime: 2012-08-25T00:00:02.000Z
    timeZone: UTC
    address1: 12 rue des ecoles
    address2: Poitier
    postalCode: 44 567
    company: Renault
    city: Quelque part
    state: Poitou
    country: France
    locale: fr
    phone: 81 53 26 56
    notes: notes
    isMigrated: false
    accountBalance: 0
    accountCBA: 0E-9
    auditLogs: []
}

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

      ]
   }
]

[
    {
     'account_balance': None,
     'account_cba': None,
     'account_id': '07c0cef4-41c5-4606-b2cd-661332cdd41c',
     'address1': None,
     'address2': None,
     'audit_logs': [],
     'bill_cycle_day_local': 0,
     'city': None,
     'company': None,
     'country': 'USA',
     'currency': 'USD',
     'email': None,
     'external_key': 'rpwtgr',
     'first_name_length': None,
     'is_migrated': False,
     'is_notified_for_invoices': False,
     'is_payment_delegated_to_parent': False,
     'locale': None,
     'name': 'John',
     'notes': None,
     'parent_account_id': None,
     'payment_method_id': None,
     'phone': None,
     'postal_code': None,
     'reference_time': datetime.datetime(2018, 5, 3, 15, 53, 44, tzinfo=tzutc()),
     'state': 'CA',
     'time_zone': 'UTC'
    }
]

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

account.transfer_child_credit(user,
                              reason,
                              comment,
                              options)

accountApi = killbill.api.AccountApi()
child_account_id = '88a5987a-1e1c-47c5-ba95-34ef14db3d46'

accountApi.transfer_child_credit_to_parent(child_account_id,
                                           created_by, 
                                           api_key, 
                                           api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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 ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

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.api.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,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: ACCOUNT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"6e571e22-b794-413c-be6f-1b2aa4bf9824",
      "objectId":"0149ffc6-fdfd-40b1-8cf4-29a66aef51d4",
      "objectType":"ACCOUNT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

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

accountApi = killbill.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.get_all_custom_fields(account_id, 
                                 api_key, 
                                 api_secret, 
                                 object_type='ACCOUNT')

object_type = 'ACCOUNT'
audit = 'NONE'

account.all_custom_fields(object_type,
                          audit, 
                          options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@238cc919
    customFieldId: dba8ec60-ee02-4231-9fa0-6613773b4e9e
    objectId: b38de59f-7dd0-447a-a508-9b022b808250
    objectType: ACCOUNT
    name: 385af
    value: 8296f
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:01.000Z
        objectType: CUSTOM_FIELD
        objectId: dba8ec60-ee02-4231-9fa0-6613773b4e9e
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: 10e278f1-61b8-4885-b1f6-d6f4db19c998
        history: null
    }]
}

[
   {
      "tagId":"ce1715f6-35e8-4d86-9063-65a54625992d",
      "objectType":"ACCOUNT",
      "objectId":"0f55a05d-9946-41d7-be75-ee71f49829b1",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000006",
      "tagDefinitionName":"TEST",
      "auditLogs":[]
   }
]

[
  {
    'audit_logs': [],
    'object_id': '8f2618dc-9e8e-4df6-b835-68c747a48313',
    'object_type': 'ACCOUNT',
    'tag_definition_id': '00000000-0000-0000-0000-000000000002',
    'tag_definition_name': 'AUTO_INVOICING_OFF',
    'tag_id': '726a64eb-0fc2-4e1b-81c4-ebf879a3b5b6'
  }
]

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

audit = 'NONE'

account.custom_fields(audit, options)

accountApi = killbill.api.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'

accountApi.get_account_custom_fields(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: ACCOUNT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"ACCOUNT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[
 {
   'audit_logs': [],
   'custom_field_id': 'd7bb1afb-df19-4db2-ba7f-9a4f71e9b131',
   'name': 'Test Custom Field',
   'object_id': '89c45186-8ab0-44f8-8bc9-e670924830a2',
   'object_type': 'ACCOUNT',
   'value': 'test_value'
 }
]

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

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.api.AccountApi()
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, 
                                     api_key, 
                                     api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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 = ImmutableList.<UUID>of(customFieldsId);
accountApi.deleteAccountCustomFields(accountId, 
                                     customFieldsList, 
                                     requestOptions);

custom_field_id = custom_field.id

account.remove_custom_field(custom_field_id, 
                            user, 
                            reason,
                            comment, 
                            options)

account = killbill.api.AccountApi()
account_id = '8992e146-bfa1-4126-a045-98b844a4adcb'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
custom_field = [custom_field_id]

account.delete_account_custom_fields(account_id,
                                     created_by,
                                     api_key,
                                     api_secret,
                                     custom_field=custom_field)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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

While custom fields allow you to attach {key, value} pairs to various objects in the system, single values can also be attached to various objects in the system by using tags. Tags come in 2 different categories:

• System Tags: These are interpreted by the system to change its behavior. Certain tags can only be attached to specific resource types -- e.g Account. In order to distinguish them from the user tags, the system tags are uppercase symbols.
• User Tags: These are not interpreted by the system and can be anything as long as it a lowercase symbol. Foe example, good_customer could be a tag that can be attached to a customer Account.

The APIs to manage tags rely on having an existing tag definition and supplying the tagDefinitionId in the calls. Therefore, for user tags, one should first create a TagDefinition.

To create user tags, one must first create the tag definitions. For instructions see section Tag definition.

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, 
                                           ImmutableList.<UUID>of(autoPayOffTagId), 
                                           requestOptions);

tag_name = 'TEST'

account.add_tag(tag_name,
                user,
                reason,
                comment,
                options)

accountApi = killbill.api.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tag = ["00000000-0000-0000-0000-000000000002"]

accountApi.create_account_tags(account_id, 
                               tag, 
                               created_by, 
                               api_key, 
                               api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/tags
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: ACCOUNT
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 00000000-0000-0000-0000-000000000001
    tagDefinitionName: AUTO_PAY_OFF
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"ACCOUNT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000006",
      "tagDefinitionName":"TEST",
      "auditLogs":[

      ]
   }
]

no content

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.api.AccountApi()
account_id = '07c0cef4-41c5-4606-b2cd-661332cdd41c'

accountApi.get_account_tags(account_id, api_key, api_secret)

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

account.all_tags(object_type, 
                 included_deleted, 
                 audit, 
                 options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@45e9c8ec
    tagId: 659b37ed-59d7-4b46-b4e4-37d11cdc0bce
    objectType: ACCOUNT
    objectId: ee6835f0-8347-42d3-958c-9a939383ba28
    tagDefinitionId: 00000000-0000-0000-0000-000000000001
    tagDefinitionName: AUTO_PAY_OFF
    auditLogs: []
}

[
   {
      "tagId":"ce1715f6-35e8-4d86-9063-65a54625992d",
      "objectType":"ACCOUNT",
      "objectId":"0f55a05d-9946-41d7-be75-ee71f49829b1",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000006",
      "tagDefinitionName":"TEST",
      "auditLogs":[]
   }
]

[
  {
    'audit_logs': [],
    'object_id': '8f2618dc-9e8e-4df6-b835-68c747a48313',
    'object_type': 'ACCOUNT',
    'tag_definition_id': '00000000-0000-0000-0000-000000000002',
    'tag_definition_name': 'AUTO_INVOICING_OFF',
    'tag_id': '726a64eb-0fc2-4e1b-81c4-ebf879a3b5b6'
  }
]

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

included_deleted = false
audit = 'NONE'

account.tags(included_deleted,
             audit,
             options)

accountApi = killbill.api.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'

accountApi.get_account_tags(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: ACCOUNT
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 00000000-0000-0000-0000-000000000001
    tagDefinitionName: AUTO_PAY_OFF
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"ACCOUNT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000006",
      "tagDefinitionName":"TEST",
      "auditLogs":[

      ]
   }
]

[
  {
    'audit_logs': [],
    'object_id': '2501dd10-8244-4b4f-9356-8cf73f18fbf6',
    'object_type': 'ACCOUNT',
    'tag_definition_id': '00000000-0000-0000-0000-000000000002',
    'tag_definition_name': 'AUTO_INVOICING_OFF',
    'tag_id': '83df059f-7529-43d4-b77b-c91f39a60166'
  }
]

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, 
                             ImmutableList.<UUID>of(autoPayOffId), 
                             requestOptions);

tag_name = 'TEST'

account.remove_tag(tag_name,
                   user,
                   reason,
                   comment,
                   options)

accountApi = killbill.api.AccountApi()
account_id = 'b0da8392-49ba-43f2-8fac-3f9f85b8ff61'
tag = ["00000000-0000-0000-0000-000000000002"]

accountApi.delete_account_tags(account_id, 
                               created_by, 
                               api_key, 
                               api_secret, 
                               tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

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

accountApi = killbill.api.AccountApi()
account_id = '4e4d8acd-c97d-447a-814b-28f995a9106c'

accountApi.get_account_audit_logs(account_id, api_key, api_secret)

account.audit(options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class AuditLog {
    changeType: INSERT
    changeDate: 2012-08-25T00:00:01.000Z
    objectType: ACCOUNT
    objectId: e9432491-6558-4007-85ef-cdae171d240c
    changedBy: Toto
    reasonCode: i am god
    comments: no comment
    userToken: 6cd7a8ec-0678-436f-a2cb-a58f9ee3668b
    history: null
}

[
   {
      "changeType":"INSERT",
      "changeDate":"2013-08-01T06:00:00.000Z",
      "objectType":"ACCOUNT",
      "objectId":"ccaf0822-a58b-4f1d-82d2-907439b68054",
      "changedBy":"test_account_tags",
      "userToken":"17d7807c-5c44-4e57-adc5-d0323c779b1f"
   }
]

[{'change_date': datetime.datetime(2018, 5, 23, 14, 30, 5, tzinfo=tzutc()),
 'change_type': 'INSERT',
 'changed_by': 'test',
 'comments': None,
 'object_id': '4e4d8acd-c97d-447a-814b-28f995a9106c',
 'object_type': 'ACCOUNT',
 'reason_code': None,
 'user_token': '89ef6e86-4869-4974-abb9-0d870e8578b2'}]

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

accountApi = killbill.api.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

accountApi.get_account_audit_logs_with_history(account_id, api_key, api_secret)

account.audit_logs_with_history(options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class AuditLog {
    changeType: INSERT
    changeDate: 2012-08-25T00:00:01.000Z
    objectType: ACCOUNT
    objectId: ecbff3be-3cbf-4e1d-ae05-d323d4597877
    changedBy: Toto
    reasonCode: i am god
    comments: no comment
    userToken: d698ba59-cacd-4739-9e40-68506ec046ca
    history: {id=null, 
              createdDate=2012-08-25T00:00:01.000Z, 
              updatedDate=2012-08-25T00:00:01.000Z, 
              recordId=1, accountRecordId=1, 
              tenantRecordId=1, 
              externalKey=5bb29c30-c83a-4237-b886-6605319baf8f, 
              email=a946d@6a7f4, 
              name=40f79b31-64eb-429b-96b5-89c05a21883f, 
              firstNameLength=4, 
              currency=USD, 
              parentAccountId=null, 
              isPaymentDelegatedToParent=false, 
              billingCycleDayLocal=0, 
              paymentMethodId=null, 
              referenceTime=2012-08-25T00:00:01.000Z, 
              timeZone=UTC, 
              locale=fr, 
              address1=12 rue des ecoles, 
              address2=Poitier, 
              companyName=Renault, 
              city=Quelque part, 
              stateOrProvince=Poitou, 
              country=France, 
              postalCode=44 567, 
              phone=81 53 26 56, 
              notes=notes, 
              migrated=false, 
              tableName=ACCOUNT, 
              historyTableName=ACCOUNT_HISTORY}
}

[
   {
      "changeType":"INSERT",
      "changeDate":"2013-08-01T06:00:00.000Z",
      "objectType":"ACCOUNT",
      "objectId":"08a1c2e4-687f-48ca-9c38-888108a2ce0a",
      "changedBy":"test_account_tags",
      "userToken":"5c0632c3-6567-4b0b-8e37-e2a9bb9ab6b2",
      "history":{
         "id":null,
         "createdDate":"2013-08-01T06:00:00.000Z",
         "updatedDate":"2013-08-01T06:00:00.000Z",
         "recordId":505,
         "accountRecordId":505,
         "tenantRecordId":822,
         "externalKey":"1527086785-621747",
         "email":"kill@bill.com",
         "name":"KillBillClient",
         "firstNameLength":null,
         "currency":"USD",
         "parentAccountId":null,
         "isPaymentDelegatedToParent":null,
         "billingCycleDayLocal":0,
         "paymentMethodId":null,
         "referenceTime":"2013-08-01T06:00:00.000Z",
         "timeZone":"UTC",
         "locale":"fr_FR",
         "address1":"7, yoyo road",
         "address2":"Apt 5",
         "companyName":"Unemployed",
         "city":"San Francisco",
         "stateOrProvince":"California",
         "country":"US",
         "postalCode":"94105",
         "phone":null,
         "notes":null,
         "migrated":null,
         "tableName":"ACCOUNT",
         "historyTableName":"ACCOUNT_HISTORY"
      }
   }
]

[{'change_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc()),
 'change_type': 'INSERT',
 'changed_by': 'test',
 'comments': None,
 'history': {'created_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc()),
             'id': None,
             'updated_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc())},
 'object_id': 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda',
 'object_type': 'ACCOUNT',
 'reason_code': None,
 'user_token': '40e771bf-160e-4ff6-82be-463f2d9e634d'}]

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

accountApi = killbill.api.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
account_email_id = 'bb390282-6757-4f4f-8dd5-456abd9f30b2'

accountApi.get_account_email_audit_logs_with_history(account_id,
                                                     account_email_id,
                                                     api_key,
                                                     api_secret)

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

account.email_audit_logs_with_history(account_email_id, options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

//First element of the list
class AuditLog {
    changeType: INSERT
    changeDate: 2012-08-25T00:00:02.000Z
    objectType: ACCOUNT_EMAIL
    objectId: f637441d-855e-4bf5-bac1-6426bdb116d6
    changedBy: Toto
    reasonCode: i am god
    comments: no comment
    userToken: 317c943b-f137-4866-9798-33c5818339f9
    history: {id=null, 
              createdDate=2012-08-25T00:00:02.000Z, 
              updatedDate=2012-08-25T00:00:02.000Z, 
              recordId=1, 
              accountRecordId=1, 
              tenantRecordId=1, 
              accountId=9f86c177-addd-48da-b734-da219b33f655, 
              email=af6c8ec2-bed8-4a86-aa23-535276aad7ca, 
              isActive=true, 
              tableName=ACCOUNT_EMAIL, 
              historyTableName=ACCOUNT_EMAIL_HISTORY}
}

[
   {
      "changeType":"INSERT",
      "changeDate":"2013-08-01T06:00:00.000Z",
      "objectType":"ACCOUNT_EMAIL",
      "objectId":"a4627e89-a73b-4167-a7ba-92a2881eb3c4",
      "changedBy":"test_account_tags",
      "userToken":"79005abf-a8cf-44e1-84fc-945381d35bd5",
      "history":{
         "id":null,
         "createdDate":"2013-08-01T06:00:00.000Z",
         "updatedDate":"2013-08-01T06:00:00.000Z",
         "recordId":18,
         "accountRecordId":525,
         "tenantRecordId":842,
         "accountId":"1ced5fc2-b032-4969-a38b-d4db9ab5368f",
         "email":"email@laposte.com",
         "isActive":true,
         "tableName":"ACCOUNT_EMAIL",
         "historyTableName":"ACCOUNT_EMAIL_HISTORY"
      }
   }
]

[{'change_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc()),
 'change_type': 'INSERT',
 'changed_by': 'Me',
 'comments': None,
 'history': {'created_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc()),
             'id': None,
             'updated_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc())},
 'object_id': 'bb390282-6757-4f4f-8dd5-456abd9f30b2',
 'object_type': 'ACCOUNT_EMAIL',
 'reason_code': None,
 'user_token': '548055b7-2c5e-4315-9293-d76c00bd9737'}]

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

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

class AuditLog {
    changeType: INSERT
    changeDate: 2021-04-29T05:07:53.000Z
    objectType: BLOCKING_STATES
    objectId: 0997b953-2b3a-4dc5-ad01-c38911662923
    changedBy: OverdueService
    reasonCode: null
    comments: null
    userToken: 01832d6c-6a67-453f-ab16-6c810245064e
    history: {id=null, createdDate=2021-04-29T05:07:53.000Z, updatedDate=2021-04-29T05:07:53.000Z, recordId=17, accountRecordId=40, tenantRecordId=1, blockableId=4747a100-460a-4e1f-aba6-4b4f71e26d7b, type=ACCOUNT, state=Warning1, service=overdue-service, blockChange=false, blockEntitlement=false, blockBilling=false, effectiveDate=2021-04-29T05:07:52.000Z, isActive=true, active=true, tableName=BLOCKING_STATES, historyTableName=BLOCKING_STATES}
}

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.api.AccountApi()
account_id = '43488882-1777-460c-bc32-e375e67d09cf'

accountApi.get_account_timeline(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "account": {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "name": "John Doe",
    "firstNameLength": null,
    "externalKey": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "email": "john@laposte.com",
    "billCycleDayLocal": 0,
    "currency": "USD",
    "parentAccountId": null,
    "isPaymentDelegatedToParent": false,
    "paymentMethodId": null,
    "referenceTime": "2018-07-17T15:02:45.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": []
  },
  "bundles": [],
  "invoices": [],
  "payments": []
}

class AccountTimeline {
    account: class Account {
        org.killbill.billing.client.model.gen.Account@15d03da
        accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
        name: 6d3aec15-0f95-4445-a4b2-03ba6f312d9f
        firstNameLength: 4
        externalKey: bf50b936-8909-442c-95d9-53302ac53a73
        email: 86aa8@349d7
        billCycleDayLocal: 25
        currency: USD
        parentAccountId: null
        isPaymentDelegatedToParent: false
        paymentMethodId: ef4e6d42-1472-4027-a991-d611701a6001
        referenceTime: 2012-04-25T00:03:42.000Z
        timeZone: UTC
        address1: 12 rue des ecoles
        address2: Poitier
        postalCode: 44 567
        company: Renault
        city: Quelque part
        state: Poitou
        country: France
        locale: fr
        phone: 81 53 26 56
        notes: notes
        isMigrated: false
        accountBalance: null
        accountCBA: null
        auditLogs: []
    }
    bundles: [class Bundle {
        org.killbill.billing.client.model.gen.Bundle@b1f3cdff
        accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
        bundleId: a077e897-3f75-47e0-af54-eb799c9ed234
        externalKey: 19149cd6-60fb-414f-a720-1b0c5d41f62a
        subscriptions: [class Subscription {
            org.killbill.billing.client.model.gen.Subscription@be14321
            accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
            bundleId: a077e897-3f75-47e0-af54-eb799c9ed234
            subscriptionId: 510470b8-4495-4215-b4ff-9dd3fb952fb6
            externalKey: 19149cd6-60fb-414f-a720-1b0c5d41f62a
            startDate: 2012-04-25
            productName: Shotgun
            productCategory: BASE
            billingPeriod: MONTHLY
            phaseType: EVERGREEN
            priceList: DEFAULT
            planName: shotgun-monthly
            state: ACTIVE
            sourceType: NATIVE
            cancelledDate: null
            chargedThroughDate: 2012-06-25
            billingStartDate: 2012-04-25
            billingEndDate: null
            billCycleDayLocal: 25
            events: [class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@c5424137
                eventId: b7220076-fe42-4fc5-9843-7296044e7f17
                billingPeriod: MONTHLY
                effectiveDate: 2012-04-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: START_ENTITLEMENT
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: entitlement-service
                serviceStateName: ENT_STARTED
                phase: shotgun-monthly-trial
                auditLogs: []
            }, class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@90c31d8f
                eventId: 8b74b94e-a41e-4018-9f84-e86870de337b
                billingPeriod: MONTHLY
                effectiveDate: 2012-04-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: START_BILLING
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: billing-service
                serviceStateName: START_BILLING
                phase: shotgun-monthly-trial
                auditLogs: []
            }, class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@a5e22a9b
                eventId: e0d9367c-a94d-4f9c-a068-4b21870d8919
                billingPeriod: MONTHLY
                effectiveDate: 2012-05-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: PHASE
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: entitlement+billing-service
                serviceStateName: PHASE
                phase: shotgun-monthly-evergreen
                auditLogs: []
            }]
            priceOverrides: [class PhasePriceOverride {
                planName: shotgun-monthly
                phaseName: shotgun-monthly-trial
                phaseType: TRIAL
                fixedPrice: 0
                recurringPrice: null
                usagePriceOverrides: []
            }, class PhasePriceOverride {
                planName: shotgun-monthly
                phaseName: shotgun-monthly-evergreen
                phaseType: EVERGREEN
                fixedPrice: null
                recurringPrice: 249.95
                usagePriceOverrides: []
            }]
            auditLogs: []
        }]
        timeline: class BundleTimeline {
            org.killbill.billing.client.model.gen.BundleTimeline@8354e44a
            accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
            bundleId: a077e897-3f75-47e0-af54-eb799c9ed234
            externalKey: 19149cd6-60fb-414f-a720-1b0c5d41f62a
            events: [class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@aaf34cbe
                eventId: b7220076-fe42-4fc5-9843-7296044e7f17
                billingPeriod: MONTHLY
                effectiveDate: 2012-04-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: START_ENTITLEMENT
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: entitlement-service
                serviceStateName: ENT_STARTED
                phase: shotgun-monthly-trial
                auditLogs: []
            }, class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@719050e7
                eventId: 8b74b94e-a41e-4018-9f84-e86870de337b
                billingPeriod: MONTHLY
                effectiveDate: 2012-04-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: START_BILLING
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: billing-service
                serviceStateName: START_BILLING
                phase: shotgun-monthly-trial
                auditLogs: []
            }, class EventSubscription {
                org.killbill.billing.client.model.gen.EventSubscription@a23e5a2c
                eventId: e0d9367c-a94d-4f9c-a068-4b21870d8919
                billingPeriod: MONTHLY
                effectiveDate: 2012-05-25
                plan: shotgun-monthly
                product: Shotgun
                priceList: DEFAULT
                eventType: PHASE
                isBlockedBilling: false
                isBlockedEntitlement: false
                serviceName: entitlement+billing-service
                serviceStateName: PHASE
                phase: shotgun-monthly-evergreen
                auditLogs: []
            }]
            auditLogs: []
        }
        auditLogs: []
    }]
    invoices: [class Invoice {
        org.killbill.billing.client.model.gen.Invoice@be958014
        amount: 0.00
        currency: USD
        status: COMMITTED
        creditAdj: 0.00
        refundAdj: 0.00
        invoiceId: 94e03bc3-ef0a-4db8-9e01-e87cabcf7dfc
        invoiceDate: 2012-04-25
        targetDate: 2012-04-25
        invoiceNumber: 1
        balance: 0.00
        accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
        bundleKeys: 19149cd6-60fb-414f-a720-1b0c5d41f62a
        credits: []
        items: null
        isParentInvoice: false
        parentInvoiceId: null
        parentAccountId: null
        auditLogs: []
    }, class Invoice {
        org.killbill.billing.client.model.gen.Invoice@54f97871
        amount: 249.95
        currency: USD
        status: COMMITTED
        creditAdj: 0.00
        refundAdj: 0.00
        invoiceId: 1b547802-6d4a-41d8-ae67-fdb209c8fd8a
        invoiceDate: 2012-05-27
        targetDate: 2012-05-25
        invoiceNumber: 2
        balance: 0.00
        accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
        bundleKeys: 19149cd6-60fb-414f-a720-1b0c5d41f62a
        credits: []
        items: null
        isParentInvoice: false
        parentInvoiceId: null
        parentAccountId: null
        auditLogs: []
    }]
    payments: [class InvoicePayment {
        org.killbill.billing.client.model.gen.InvoicePayment@e8067ccf
        targetInvoiceId: 1b547802-6d4a-41d8-ae67-fdb209c8fd8a
        accountId: 16364ac4-2a77-4444-b2d8-e980c37a8954
        paymentId: ff4f3e17-708c-4f83-a648-1c45a0b9fdf0
        paymentNumber: 1
        paymentExternalKey: ff4f3e17-708c-4f83-a648-1c45a0b9fdf0
        authAmount: 0
        capturedAmount: 0
        purchasedAmount: 249.95
        refundedAmount: 0
        creditedAmount: 0
        currency: USD
        paymentMethodId: ef4e6d42-1472-4027-a991-d611701a6001
        transactions: [class PaymentTransaction {
            org.killbill.billing.client.model.gen.PaymentTransaction@868031c1
            transactionId: 50b13522-6853-4aa5-85ba-aa12bbd643cc
            transactionExternalKey: 50b13522-6853-4aa5-85ba-aa12bbd643cc
            paymentId: ff4f3e17-708c-4f83-a648-1c45a0b9fdf0
            paymentExternalKey: ff4f3e17-708c-4f83-a648-1c45a0b9fdf0
            transactionType: PURCHASE
            amount: 249.95
            currency: USD
            effectiveDate: 2012-05-27T00:03:45.000Z
            processedAmount: 249.95
            processedCurrency: USD
            status: SUCCESS
            gatewayErrorCode: 
            gatewayErrorMsg: 
            firstPaymentReferenceId: null
            secondPaymentReferenceId: null
            properties: null
            auditLogs: []
        }]
        paymentAttempts: null
        auditLogs: []
    }]
}

{
   "account":{
      "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
      "name":"KillBillClient",
      "externalKey":"1522173024-759445",
      "email":"kill@bill.com",
      "billCycleDayLocal":31,
      "currency":"USD",
      "isPaymentDelegatedToParent":false,
      "timeZone":"UTC",
      "address1":"7, yoyo road",
      "address2":"Apt 5",
      "postalCode":"94105",
      "company":"Unemployed",
      "city":"San Francisco",
      "state":"California",
      "country":"US",
      "locale":"fr_FR",
      "auditLogs":[
         {
            "changeType":"INSERT",
            "changeDate":"2013-08-01T06:00:01.000Z",
            "changedBy":"test_change_default",
            "userToken":"07952a10-4283-456a-830d-0b2a1e353eec"
         }
      ]
   },
   "bundles":[
      {
         "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
         "bundleId":"043b06e0-7d61-4891-ab58-63b02eaf0fee",
         "externalKey":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69-478447",
         "subscriptions":[
            {
               "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
               "bundleId":"043b06e0-7d61-4891-ab58-63b02eaf0fee",
               "subscriptionId":"c1675495-e899-4e1e-8d81-8ef02b02e0a8",
               "externalKey":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69-478447",
               "startDate":"2013-08-01",
               "productName":"Super",
               "productCategory":"BASE",
               "billingPeriod":"MONTHLY",
               "phaseType":"TRIAL",
               "priceList":"DEFAULT",
               "planName":"super-monthly",
               "state":"ACTIVE",
               "sourceType":"NATIVE",
               "chargedThroughDate":"2013-08-02",
               "billingStartDate":"2013-08-01",
               "billCycleDayLocal":31,
               "events":[
                  {
                     "eventId":"97a0172a-cb88-467b-bbaf-28cf3a335570",
                     "billingPeriod":"MONTHLY",
                     "effectiveDate":"2013-08-01",
                     "plan":"sports-monthly",
                     "product":"Sports",
                     "priceList":"DEFAULT",
                     "eventType":"START_ENTITLEMENT",
                     "isBlockedBilling":false,
                     "isBlockedEntitlement":false,
                     "serviceName":"entitlement-service",
                     "serviceStateName":"ENT_STARTED",
                     "phase":"sports-monthly-trial",
                     "auditLogs":[
                        {
                           "changeType":"INSERT",
                           "changeDate":"2013-08-01T06:00:01.000Z",
                           "changedBy":"test_change_default",
                           "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
                        }
                     ]
                  },
                  {
                     "eventId":"b634594b-6680-4456-a083-521301416e31",
                     "billingPeriod":"MONTHLY",
                     "effectiveDate":"2013-08-01",
                     "plan":"sports-monthly",
                     "product":"Sports",
                     "priceList":"DEFAULT",
                     "eventType":"START_BILLING",
                     "isBlockedBilling":false,
                     "isBlockedEntitlement":false,
                     "serviceName":"billing-service",
                     "serviceStateName":"START_BILLING",
                     "phase":"sports-monthly-trial",
                     "auditLogs":[
                        {
                           "changeType":"INSERT",
                           "changeDate":"2013-08-01T06:00:01.000Z",
                           "changedBy":"test_change_default",
                           "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
                        }
                     ]
                  },
                  {
                     "eventId":"82953028-68c0-4c2e-9596-0248047d2452",
                     "billingPeriod":"MONTHLY",
                     "effectiveDate":"2013-08-02",
                     "plan":"super-monthly",
                     "product":"Super",
                     "priceList":"DEFAULT",
                     "eventType":"CHANGE",
                     "isBlockedBilling":false,
                     "isBlockedEntitlement":false,
                     "serviceName":"entitlement+billing-service",
                     "serviceStateName":"CHANGE",
                     "phase":"super-monthly-trial",
                     "auditLogs":[
                        {
                           "changeType":"INSERT",
                           "changeDate":"2013-08-02T06:00:03.000Z",
                           "changedBy":"test_change_default",
                           "userToken":"7e39f68b-c695-4d38-822b-5e4ad230f130"
                        }
                     ]
                  },
                  {
                     "eventId":"c2e120b7-af1a-42f4-b16d-2669be94c897",
                     "billingPeriod":"MONTHLY",
                     "effectiveDate":"2013-08-31",
                     "plan":"super-monthly",
                     "product":"Super",
                     "priceList":"DEFAULT",
                     "eventType":"PHASE",
                     "isBlockedBilling":false,
                     "isBlockedEntitlement":false,
                     "serviceName":"entitlement+billing-service",
                     "serviceStateName":"PHASE",
                     "phase":"super-monthly-evergreen",
                     "auditLogs":[
                        {
                           "changeType":"INSERT",
                           "changeDate":"2013-08-02T06:00:03.000Z",
                           "changedBy":"test_change_default",
                           "userToken":"7e39f68b-c695-4d38-822b-5e4ad230f130"
                        }
                     ]
                  }
               ],
               "priceOverrides":[
                  {
                     "planName":"sports-monthly",
                     "phaseName":"sports-monthly-trial",
                     "phaseType":"TRIAL",
                     "fixedPrice":0
                  },
                  {
                     "planName":"super-monthly",
                     "phaseName":"super-monthly-trial",
                     "phaseType":"TRIAL",
                     "fixedPrice":0
                  },
                  {
                     "planName":"super-monthly",
                     "phaseName":"super-monthly-evergreen",
                     "phaseType":"EVERGREEN",
                     "recurringPrice":1000.0
                  }
               ],
               "auditLogs":[
                  {
                     "changeType":"INSERT",
                     "changeDate":"2013-08-01T06:00:01.000Z",
                     "changedBy":"test_change_default",
                     "reasonCode":null,
                     "comments":null,
                     "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
                  }
               ]
            }
         ],
         "timeline":{
            "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
            "bundleId":"043b06e0-7d61-4891-ab58-63b02eaf0fee",
            "externalKey":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69-478447",
            "events":[
               {
                  "eventId":"97a0172a-cb88-467b-bbaf-28cf3a335570",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"sports-monthly",
                  "product":"Sports",
                  "priceList":"DEFAULT",
                  "eventType":"START_ENTITLEMENT",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement-service",
                  "serviceStateName":"ENT_STARTED",
                  "phase":"sports-monthly-trial",
                  "auditLogs":[
                     {
                        "changeType":"INSERT",
                        "changeDate":"2013-08-01T06:00:01.000Z",
                        "changedBy":"test_change_default",
                        "reasonCode":null,
                        "comments":null,
                        "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
                     }
                  ]
               },
               {
                  "eventId":"b634594b-6680-4456-a083-521301416e31",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-01",
                  "plan":"sports-monthly",
                  "product":"Sports",
                  "priceList":"DEFAULT",
                  "eventType":"START_BILLING",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"billing-service",
                  "serviceStateName":"START_BILLING",
                  "phase":"sports-monthly-trial",
                  "auditLogs":[
                     {
                        "changeType":"INSERT",
                        "changeDate":"2013-08-01T06:00:01.000Z",
                        "changedBy":"test_change_default",
                        "reasonCode":null,
                        "comments":null,
                        "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
                     }
                  ]
               },
               {
                  "eventId":"82953028-68c0-4c2e-9596-0248047d2452",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-02",
                  "plan":"super-monthly",
                  "product":"Super",
                  "priceList":"DEFAULT",
                  "eventType":"CHANGE",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement+billing-service",
                  "serviceStateName":"CHANGE",
                  "phase":"super-monthly-trial",
                  "auditLogs":[
                     {
                        "changeType":"INSERT",
                        "changeDate":"2013-08-02T06:00:03.000Z",
                        "changedBy":"test_change_default",
                        "reasonCode":null,
                        "comments":null,
                        "userToken":"7e39f68b-c695-4d38-822b-5e4ad230f130"
                     }
                  ]
               },
               {
                  "eventId":"c2e120b7-af1a-42f4-b16d-2669be94c897",
                  "billingPeriod":"MONTHLY",
                  "effectiveDate":"2013-08-31",
                  "plan":"super-monthly",
                  "product":"Super",
                  "priceList":"DEFAULT",
                  "eventType":"PHASE",
                  "isBlockedBilling":false,
                  "isBlockedEntitlement":false,
                  "serviceName":"entitlement+billing-service",
                  "serviceStateName":"PHASE",
                  "phase":"super-monthly-evergreen",
                  "auditLogs":[
                     {
                        "changeType":"INSERT",
                        "changeDate":"2013-08-02T06:00:03.000Z",
                        "changedBy":"test_change_default",
                        "reasonCode":null,
                        "comments":null,
                        "userToken":"7e39f68b-c695-4d38-822b-5e4ad230f130"
                     }
                  ]
               }
            ],
            "auditLogs":[
               {
                  "changeType":"INSERT",
                  "changeDate":"2013-08-01T06:00:01.000Z",
                  "changedBy":"test_change_default",
                  "reasonCode":null,
                  "comments":null,
                  "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
               }
            ]
         },
         "auditLogs":[
            {
               "changeType":"INSERT",
               "changeDate":"2013-08-01T06:00:01.000Z",
               "changedBy":"test_change_default",
               "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
            }
         ]
      }
   ],
   "invoices":[
      {
         "amount":0.0,
         "currency":"USD",
         "status":"COMMITTED",
         "creditAdj":0.0,
         "refundAdj":0.0,
         "invoiceId":"5f7edbcd-5f38-410b-93e0-d6959c44ca25",
         "invoiceDate":"2013-08-01",
         "targetDate":"2013-08-01",
         "invoiceNumber":"1631",
         "balance":0.0,
         "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
         "bundleKeys":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69-478447",
         "credits":[],
         "isParentInvoice":false,
         "auditLogs":[
            {
               "changeType":"INSERT",
               "changeDate":"2013-08-01T06:00:02.000Z",
               "changedBy":"SubscriptionBaseTransition",
               "userToken":"cc3b9ec7-d55b-400b-803c-4a7f9413fe33"
            }
         ]
      },
      {
         "amount":0.0,
         "currency":"USD",
         "status":"COMMITTED",
         "creditAdj":0.0,
         "refundAdj":0.0,
         "invoiceId":"c68044ed-7f94-4766-b95b-a04d1484728b",
         "invoiceDate":"2013-08-02",
         "targetDate":"2013-08-02",
         "invoiceNumber":"1632",
         "balance":0.0,
         "accountId":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69",
         "bundleKeys":"f5ac6a12-7e24-4b5b-acf0-3f16436faf69-478447",
         "credits":[],
         "isParentInvoice":false,
         "auditLogs":[
            {
               "changeType":"INSERT",
               "changeDate":"2013-08-02T06:00:03.000Z",
               "changedBy":"SubscriptionBaseTransition",
               "userToken":"7e39f68b-c695-4d38-822b-5e4ad230f130"
            }
         ]
      }
   ],
   "payments":[]
}

{'account': {'account_balance': None,
             'account_cba': None,
             'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
             'address1': None,
             'address2': None,
             'audit_logs': [],
             'bill_cycle_day_local': 3,
             'city': None,
             'company': None,
             'country': 'USA',
             'currency': 'USD',
             'email': None,
             'external_key': 'hmwgix',
             'first_name_length': None,
             'is_migrated': False,
             'is_notified_for_invoices': True,
             'is_payment_delegated_to_parent': False,
             'locale': None,
             'name': 'John',
             'notes': None,
             'parent_account_id': None,
             'payment_method_id': None,
             'phone': None,
             'postal_code': None,
             'reference_time': datetime.datetime(2018, 5, 4, 19, 28, 56, tzinfo=tzutc()),
             'state': 'CA',
             'time_zone': 'UTC'},
 'bundles': [{'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
              'audit_logs': [],
              'bundle_id': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
              'external_key': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
              'subscriptions': [{'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
                                 'audit_logs': [],
                                 'bill_cycle_day_local': 3,
                                 'billing_end_date': datetime.date(2018, 5, 4),
                                 'billing_period': 'MONTHLY',
                                 'billing_start_date': datetime.date(2018, 5, 4),
                                 'bundle_id': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
                                 'cancelled_date': datetime.date(2018, 5, 4),
                                 'charged_through_date': datetime.date(2018, 5, 4),
                                 'events': [{'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': 'e2ba3b83-d04a-4128-8dea-b71d0c2a5630',
                                             'event_type': 'START_ENTITLEMENT',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'standard-monthly-trial',
                                             'plan': 'standard-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Standard',
                                             'service_name': 'entitlement-service',
                                             'service_state_name': 'ENT_STARTED'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': 'b6f9c977-a34d-4399-bd7b-c53a16aa56b2',
                                             'event_type': 'START_BILLING',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'standard-monthly-trial',
                                             'plan': 'standard-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Standard',
                                             'service_name': 'billing-service',
                                             'service_state_name': 'START_BILLING'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': 'a870def0-b47f-4513-a8fb-585df3b6b4b8',
                                             'event_type': 'CHANGE',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'super-monthly-trial',
                                             'plan': 'super-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Super',
                                             'service_name': 'entitlement+billing-service',
                                             'service_state_name': 'CHANGE'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': '96a74b51-7d51-4ec7-9386-63a07d007281',
                                             'event_type': 'STOP_ENTITLEMENT',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': True,
                                             'phase': 'super-monthly-trial',
                                             'plan': 'super-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Super',
                                             'service_name': 'entitlement-service',
                                             'service_state_name': 'ENT_CANCELLED'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': '068821fe-165c-4f67-95c1-3f14e872a27c',
                                             'event_type': 'STOP_BILLING',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'super-monthly-trial',
                                             'plan': 'super-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Super',
                                             'service_name': 'billing-service',
                                             'service_state_name': 'STOP_BILLING'}],
                                 'external_key': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
                                 'phase_type': 'TRIAL',
                                 'plan_name': 'super-monthly',
                                 'price_list': 'DEFAULT',
                                 'price_overrides': [{'fixed_price': 0.0,
                                                      'phase_name': 'standard-monthly-trial',
                                                      'phase_type': 'TRIAL',
                                                      'plan_name': 'standard-monthly',
                                                      'recurring_price': None,
                                                      'usage_price_overrides': []},
                                                     {'fixed_price': 0.0,
                                                      'phase_name': 'super-monthly-trial',
                                                      'phase_type': 'TRIAL',
                                                      'plan_name': 'super-monthly',
                                                      'recurring_price': None,
                                                      'usage_price_overrides': []}],
                                 'product_category': 'BASE',
                                 'product_name': 'Super',
                                 'source_type': 'NATIVE',
                                 'start_date': datetime.date(2018, 5, 4),
                                 'state': 'CANCELLED',
                                 'subscription_id': 'dfd4af5d-a72e-420e-9e0a-ce600d108b3f'}],
              'timeline': {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
                           'audit_logs': [],
                           'bundle_id': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
                           'events': [{'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': 'e2ba3b83-d04a-4128-8dea-b71d0c2a5630',
                                       'event_type': 'START_ENTITLEMENT',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'standard-monthly-trial',
                                       'plan': 'standard-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Standard',
                                       'service_name': 'entitlement-service',
                                       'service_state_name': 'ENT_STARTED'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': 'b6f9c977-a34d-4399-bd7b-c53a16aa56b2',
                                       'event_type': 'START_BILLING',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'standard-monthly-trial',
                                       'plan': 'standard-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Standard',
                                       'service_name': 'billing-service',
                                       'service_state_name': 'START_BILLING'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': 'a870def0-b47f-4513-a8fb-585df3b6b4b8',
                                       'event_type': 'CHANGE',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'super-monthly-trial',
                                       'plan': 'super-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Super',
                                       'service_name': 'entitlement+billing-service',
                                       'service_state_name': 'CHANGE'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': '96a74b51-7d51-4ec7-9386-63a07d007281',
                                       'event_type': 'STOP_ENTITLEMENT',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': True,
                                       'phase': 'super-monthly-trial',
                                       'plan': 'super-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Super',
                                       'service_name': 'entitlement-service',
                                       'service_state_name': 'ENT_CANCELLED'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': '068821fe-165c-4f67-95c1-3f14e872a27c',
                                       'event_type': 'STOP_BILLING',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'super-monthly-trial',
                                       'plan': 'super-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Super',
                                       'service_name': 'billing-service',
                                       'service_state_name': 'STOP_BILLING'}],
                           'external_key': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158'}},
             {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
              'audit_logs': [],
              'bundle_id': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a',
              'external_key': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a',
              'subscriptions': [{'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
                                 'audit_logs': [],
                                 'bill_cycle_day_local': 3,
                                 'billing_end_date': None,
                                 'billing_period': 'MONTHLY',
                                 'billing_start_date': datetime.date(2018, 5, 4),
                                 'bundle_id': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a',
                                 'cancelled_date': None,
                                 'charged_through_date': datetime.date(2018, 5, 4),
                                 'events': [{'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': '4d4bde32-7bb9-448d-8066-aa67dea56658',
                                             'event_type': 'START_ENTITLEMENT',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'standard-monthly-trial',
                                             'plan': 'standard-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Standard',
                                             'service_name': 'entitlement-service',
                                             'service_state_name': 'ENT_STARTED'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 5, 4),
                                             'event_id': '4d8f7354-f4f7-43c5-bfae-353b6b8c2a0c',
                                             'event_type': 'START_BILLING',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'standard-monthly-trial',
                                             'plan': 'standard-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Standard',
                                             'service_name': 'billing-service',
                                             'service_state_name': 'START_BILLING'},
                                            {'audit_logs': [],
                                             'billing_period': 'MONTHLY',
                                             'effective_date': datetime.date(2018, 6, 3),
                                             'event_id': '7d22b380-8796-420c-b0c2-3f7b71b7a171',
                                             'event_type': 'PHASE',
                                             'is_blocked_billing': False,
                                             'is_blocked_entitlement': False,
                                             'phase': 'standard-monthly-evergreen',
                                             'plan': 'standard-monthly',
                                             'price_list': 'DEFAULT',
                                             'product': 'Standard',
                                             'service_name': 'entitlement+billing-service',
                                             'service_state_name': 'PHASE'}],
                                 'external_key': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a',
                                 'phase_type': 'TRIAL',
                                 'plan_name': 'standard-monthly',
                                 'price_list': 'DEFAULT',
                                 'price_overrides': [{'fixed_price': 0.0,
                                                      'phase_name': 'standard-monthly-trial',
                                                      'phase_type': 'TRIAL',
                                                      'plan_name': 'standard-monthly',
                                                      'recurring_price': None,
                                                      'usage_price_overrides': []},
                                                     {'fixed_price': None,
                                                      'phase_name': 'standard-monthly-evergreen',
                                                      'phase_type': 'EVERGREEN',
                                                      'plan_name': 'standard-monthly',
                                                      'recurring_price': 100.0,
                                                      'usage_price_overrides': []}],
                                 'product_category': 'BASE',
                                 'product_name': 'Standard',
                                 'source_type': 'NATIVE',
                                 'start_date': datetime.date(2018, 5, 4),
                                 'state': 'ACTIVE',
                                 'subscription_id': '1a1f9e33-7720-4655-a74e-0ecf0a8f231e'}],
              'timeline': {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
                           'audit_logs': [],
                           'bundle_id': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a',
                           'events': [{'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': '4d4bde32-7bb9-448d-8066-aa67dea56658',
                                       'event_type': 'START_ENTITLEMENT',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'standard-monthly-trial',
                                       'plan': 'standard-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Standard',
                                       'service_name': 'entitlement-service',
                                       'service_state_name': 'ENT_STARTED'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 5, 4),
                                       'event_id': '4d8f7354-f4f7-43c5-bfae-353b6b8c2a0c',
                                       'event_type': 'START_BILLING',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'standard-monthly-trial',
                                       'plan': 'standard-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Standard',
                                       'service_name': 'billing-service',
                                       'service_state_name': 'START_BILLING'},
                                      {'audit_logs': [],
                                       'billing_period': 'MONTHLY',
                                       'effective_date': datetime.date(2018, 6, 3),
                                       'event_id': '7d22b380-8796-420c-b0c2-3f7b71b7a171',
                                       'event_type': 'PHASE',
                                       'is_blocked_billing': False,
                                       'is_blocked_entitlement': False,
                                       'phase': 'standard-monthly-evergreen',
                                       'plan': 'standard-monthly',
                                       'price_list': 'DEFAULT',
                                       'product': 'Standard',
                                       'service_name': 'entitlement+billing-service',
                                       'service_state_name': 'PHASE'}],
                           'external_key': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a'}}],
 'invoices': [{'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
               'amount': 0.0,
               'audit_logs': [],
               'balance': 0.0,
               'bundle_keys': 'c3fbb8a6-f297-41e5-8aa5-8098256b624a,b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
               'credit_adj': 0.0,
               'credits': [],
               'currency': 'USD',
               'invoice_date': datetime.date(2018, 5, 4),
               'invoice_id': '0c047109-6fba-4910-af8d-a200abbba5fb',
               'invoice_number': '798',
               'is_parent_invoice': False,
               'items': None,
               'parent_account_id': None,
               'parent_invoice_id': None,
               'refund_adj': 0.0,
               'status': 'COMMITTED',
               'target_date': datetime.date(2018, 5, 4)},
              {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
               'amount': 0.0,
               'audit_logs': [],
               'balance': 0.0,
               'bundle_keys': 'b769c9ec-0a13-4a8a-b686-c5bf1e56c158',
               'credit_adj': 0.0,
               'credits': [],
               'currency': 'USD',
               'invoice_date': datetime.date(2018, 5, 4),
               'invoice_id': 'fa2f6484-530c-4209-884e-d09af0766663',
               'invoice_number': '799',
               'is_parent_invoice': False,
               'items': None,
               'parent_account_id': None,
               'parent_invoice_id': None,
               'refund_adj': 0.0,
               'status': 'COMMITTED',
               'target_date': datetime.date(2018, 5, 4)},
              {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
               'amount': 50.0,
               'audit_logs': [],
               'balance': 0.0,
               'bundle_keys': '',
               'credit_adj': 0.0,
               'credits': [],
               'currency': 'USD',
               'invoice_date': datetime.date(2018, 5, 4),
               'invoice_id': 'f12c98c1-782b-4d1a-bfb0-2e1233cf8cd7',
               'invoice_number': '800',
               'is_parent_invoice': False,
               'items': None,
               'parent_account_id': None,
               'parent_invoice_id': None,
               'refund_adj': 0.0,
               'status': 'COMMITTED',
               'target_date': datetime.date(2018, 5, 4)}],
 'payments': [{'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
               'audit_logs': [],
               'auth_amount': 0.0,
               'captured_amount': 0.0,
               'credited_amount': 0.0,
               'currency': 'USD',
               'payment_attempts': None,
               'payment_external_key': 'e9733c81-5d64-4d61-add2-90cb141ddf9d',
               'payment_id': 'e9733c81-5d64-4d61-add2-90cb141ddf9d',
               'payment_method_id': '53b35b7b-e254-4c4b-b526-202c51a6e650',
               'payment_number': '309',
               'purchased_amount': 50.0,
               'refunded_amount': 0.0,
               'target_invoice_id': 'f12c98c1-782b-4d1a-bfb0-2e1233cf8cd7',
               'transactions': [{'amount': 50.0,
                                 'audit_logs': [],
                                 'currency': 'USD',
                                 'effective_date': datetime.datetime(2018, 5, 4, 19, 29, 5, tzinfo=tzutc()),
                                 'first_payment_reference_id': None,
                                 'gateway_error_code': None,
                                 'gateway_error_msg': None,
                                 'payment_external_key': 'e9733c81-5d64-4d61-add2-90cb141ddf9d',
                                 'payment_id': 'e9733c81-5d64-4d61-add2-90cb141ddf9d',
                                 'processed_amount': 50.0,
                                 'processed_currency': 'USD',
                                 'properties': None,
                                 'second_payment_reference_id': None,
                                 'status': 'SUCCESS',
                                 'transaction_external_key': '74a7f569-8f0f-48c9-a927-a56e5c96f95b',
                                 'transaction_id': '74a7f569-8f0f-48c9-a927-a56e5c96f95b',
                                 'transaction_type': 'PURCHASE'}]},
              {'account_id': '43488882-1777-460c-bc32-e375e67d09cf',
               'audit_logs': [],
               'auth_amount': 50.0,
               'captured_amount': 0.0,
               'credited_amount': 0.0,
               'currency': 'USD',
               'payment_attempts': None,
               'payment_external_key': 'f2c8e79f-49cc-4893-98a5-38da61564949',
               'payment_id': 'f2c8e79f-49cc-4893-98a5-38da61564949',
               'payment_method_id': '53b35b7b-e254-4c4b-b526-202c51a6e650',
               'payment_number': '310',
               'purchased_amount': 0.0,
               'refunded_amount': 0.0,
               'target_invoice_id': None,
               'transactions': [{'amount': 50.0,
                                 'audit_logs': [],
                                 'currency': 'USD',
                                 'effective_date': datetime.datetime(2018, 5, 4, 19, 29, 5, tzinfo=tzutc()),
                                 'first_payment_reference_id': None,
                                 'gateway_error_code': None,
                                 'gateway_error_msg': None,
                                 'payment_external_key': 'f2c8e79f-49cc-4893-98a5-38da61564949',
                                 'payment_id': 'f2c8e79f-49cc-4893-98a5-38da61564949',
                                 'processed_amount': 50.0,
                                 'processed_currency': 'USD',
                                 'properties': None,
                                 'second_payment_reference_id': None,
                                 'status': 'SUCCESS',
                                 'transaction_external_key': '0b50c1a2-99df-48df-bd6b-38e30261c233',
                                 'transaction_id': '0b50c1a2-99df-48df-bd6b-38e30261c233',
                                 'transaction_type': 'AUTHORIZE'}]}]}

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.

Payment Method

Payment Method Resource

The Payment Method resource represents the payment methods associated with a customer Account. There are two parts to the state associated with this resource, a first generic set of attributes kept by Kill Bill core subsystem, and another set of attributes kept at the (payment) plugin level.

• The core Kill Bill attributes shown below mostly track the associated payment plugin that is used to interact with the payment gateway.
• The plugin attributes are typically the details about such customer payment method: In the case of a credit card for instance, the plugin would keep track of things like name, address, last4, and token. Not only are such attributes dependent on the payment method, but they are also dependent on the third party payment gateway, and on the tokenization model, which is why they are kept by the plugin (internal tables), and not by the Kill Bill core payment subsystem.

Kill Bill also supports a more advanced use case for payment routing, where the choice of the payment gateway is decided at run time based on custom business rules. Additional information can be found in our Payment Manual.

The Kill Bill attributes are the following:

Name	Type	Generated by	Description
paymentMethodId	string	system	UUID for this payment method
externalKey	string	user	Optional external key provided by the client
accountId	string	system	UUID for the associated account
isDefault	boolean	user	Indicates whether this is the default payment method
pluginName	string	user	Name of the associated plugin.
pluginInfo	string	user	Plugin specific information, as required.

All payment operations associated with this payment method will be delegated to the plugin specified by pluginName.

Payment Methods

Basic operations to retrieve, list, search and delete payment methods.

Note that the creation of a payment method relies on an operation listed under the Account resource. The creation of a Kill Bill PaymentMethod is always associated with a given Account and it identifies (through its pluginName attribute) the payment plugin that will be used by the system when a payment is made.

Retrieve a payment method by id

Retrieve information on a payment method, given its payment method ID.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}

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/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
Boolean includedDeleted = false; // Will not include deleted
Boolean withPluginInfo = true; // Will include plugin info
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentMethod paymentMethodJson = paymentMethodApi.getPaymentMethod(paymentMethodId, 
                                                                    includedDeleted, 
                                                                    withPluginInfo, 
                                                                    NULL_PLUGIN_PROPERTIES, 
                                                                    AuditLevel.NONE, 
                                                                    requestOptions);

payment_method_id = "6a0bf13e-d57f-4f79-84bd-3690135f1923"
with_plugin_info = false

KillBillClient::Model::PaymentMethod.find_by_id(payment_method_id, 
                                                with_plugin_info, 
                                                options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '0052cddd-0f61-4f68-b653-ca49b5d7f915'

paymentMethodApi.get_payment_method(payment_method_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
{
    "paymentMethodId":"916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey":"coolPaymentMethod",
    "accountId":"84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault":false,
    "pluginName":"__EXTERNAL_PAYMENT__",
    "pluginInfo":null,
    "auditLogs":[]
}

class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@c789046
    paymentMethodId: 3c449da6-7ec4-4c74-813f-f5055739a0b9
    externalKey: 7c13b1fb-5fa5-49cb-bbb6-50b0fa78a988
    accountId: 2b995dde-ce30-451f-8bbf-5bb9ed312505
    isDefault: true
    pluginName: noop
    pluginInfo: class PaymentMethodPluginDetail {
        externalPaymentMethodId: afcdfd42-1bad-4caf-86be-93a27da51c55
        isDefaultPaymentMethod: false
        properties: [class PluginProperty {
            key: CC_NAME
            value: Bozo
            isUpdatable: false
        }, class PluginProperty {
            key: CC_CITY
            value: SF
            isUpdatable: false
        }, class PluginProperty {
            key: CC_LAST_4
            value: 4365
            isUpdatable: false
        }, class PluginProperty {
            key: CC_STATE
            value: CA
            isUpdatable: false
        }, class PluginProperty {
            key: CC_COUNTRY
            value: Zimbawe
            isUpdatable: false
        }]
    }
    auditLogs: []
}

{
   "paymentMethodId":"6a0bf13e-d57f-4f79-84bd-3690135f1923",
   "externalKey":"unknown",
   "accountId":"f9c4801f-0daa-4c46-bea0-59490d07fc5e",
   "isDefault":false,
   "pluginName":"__EXTERNAL_PAYMENT__",
   "pluginInfo":{
      "properties":[]
   },
   "auditLogs":[]
}

{'account_id': '9f2f95b9-7021-4645-9863-30feac25841a',
 'audit_logs': [],
 'external_key': 'unknown',
 'is_default': False,
 'payment_method_id': '0052cddd-0f61-4f68-b653-ca49b5d7f915',
 'plugin_info': None,
 'plugin_name': '__EXTERNAL_PAYMENT__'}

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted payment methods
withPluginInfo	boolean	no	false	If true, include plugin info
audit	string	no	"NONE"	Level of audit information to return

If withPluginInfo is set to true, attributes for the active plugin are returned. These are plugin-dependent (see discussion above). Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a payment method resource object.

Retrieve a payment method by external key

HTTP Request

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

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/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19?externalKey=coolPaymentMethod' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

String externalKey = "foo";
Boolean includedDeleted = false; // Will not include deleted
Boolean withPluginInfo = false; // Will not reflect plugin info
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentMethod paymentMethod = paymentMethodApi.getPaymentMethodByKey(externalKey, 
                                                                     includedDeleted,
                                                                     withPluginInfo,
                                                                     NULL_PLUGIN_PROPERTIES, 
                                                                     AuditLevel.NONE,
                                                                     requestOptions);

payment_method_ek = "sample_external_key"
included_deleted = false
with_plugin_info = false
audit = 'NONE'

KillBillClient::Model::PaymentMethod.find_by_external_key(payment_method_ek,
                                                          included_deleted,
                                                          with_plugin_info,
                                                          audit,
                                                          options)

paymentMethodApi = killbill.api.PaymentMethodApi()
external_key = 'sample_external_key'

paymentMethodApi.get_payment_method_by_key(external_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
{
    "paymentMethodId":"916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey":"coolPaymentMethod",
    "accountId":"84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault":false,
    "pluginName":"__EXTERNAL_PAYMENT__",
    "pluginInfo":null,
    "auditLogs":[]
}

class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@360d34cd
    paymentMethodId: c46dbe85-a14b-4d5b-8b0d-e6a07b7ff111
    externalKey: foo
    accountId: dae298f7-62b0-4774-a213-92f968693cdc
    isDefault: true
    pluginName: noop
    pluginInfo: null
    auditLogs: []
}

{
   "paymentMethodId":"4307ac7c-04a7-41e1-9cb0-8a4d4420104c",
   "externalKey":"sample_external_key",
   "accountId":"aba041a0-52f3-4d0d-b8e0-dec442dbc51e",
   "isDefault":true,
   "pluginName":"__EXTERNAL_PAYMENT__",
   "pluginInfo":{
      "properties":[]
   },
   "auditLogs":[]
}

{'account_id': '1d1c63ae-fd71-4e0c-87d4-24a334335c49',
 'audit_logs': [],
 'external_key': 'sample_external_key',
 'is_default': False,
 'payment_method_id': '882b2fa0-5946-487a-933c-b2572ea4383c',
 'plugin_info': None,
 'plugin_name': '__EXTERNAL_PAYMENT__'}

Query Parameters

Name	Type	Required	Default	Description
externalKey	string	yes	none	External key
includedDeleted	boolean	no	false	If true, include deleted payment methods
withPluginInfo	boolean	no	false	If true, include plugin info
audit	string	no	"NONE"	Level of audit information to return

If withPluginInfo is set to true, attributes for the active plugin are returned. These are plugin-dependent (see discussion above). Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a payment method resource object.

Delete a payment method

This API deletes a payment method. The default payment method may not be deleted, depending on the query parameters.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19'  

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
Boolean deleteDefaultPmWithAutoPayOff = true; // Will delete default payment method with auto pay off
Boolean forceDefaultPmDeletion = true; // Will force default payment method deletion
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentMethodApi.deletePaymentMethod(paymentMethodId, 
                                     deleteDefaultPmWithAutoPayOff, 
                                     forceDefaultPmDeletion, 
                                     NULL_PLUGIN_PROPERTIES, 
                                     requestOptions);

payment_method_id = "4307ac7c-04a7-41e1-9cb0-8a4d4420104c"
set_auto_pay_off = false
force_default_deletion = false
KillBillClient::Model::PaymentMethod.destroy(payment_method_id,
                                             set_auto_pay_off,
                                             force_default_deletion,
                                             user,
                                             reason,
                                             comment,
                                             options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '0052cddd-0f61-4f68-b653-ca49b5d7f915'

paymentMethodApi.delete_payment_method(payment_method_id, 
                                       created_by, 
                                       api_key, 
                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content  

Query Parameters

Name	Type	Required	Default	Description
deleteDefaultPmWithAutoPayOff	boolean	no	false	if true, delete default payment method only if AUTO_PAY_OFF is set
forceDefaultPmDeletion	boolean	no	false	if true, force default payment method deletion

The query parameters determine the behavior if the payment method specified is the default method: If forceDefaultPmDeletion is true, the payment method will be deleted unconditionally. If deleteDefaultPmWithAutoPayOff is true, the payment method will also be deleted, and AUTO_PAY_OFF will be set (if not already). If neither parameter is true, the default payment method will not be deleted (the call will fail).

Response

If successful, returns a status code of 204 and an empty body. If the payment method is the default and cannot be deleted, an error code of 500 and a suitable message will be returned.

List and Search

These endpoints provide the ability to list and search for payment methods for a specific tenant

List payment methods

List all payment methods stored for the accounts maintained by this tenant

HTTP Request

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

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/paymentMethods/pagination' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

Long offset = 0L;
Long limit = 1L;
String pluginName = null;
Boolean withPluginInfo = false;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;


PaymentMethods allPaymentMethods = paymentMethodApi.getPaymentMethods(offset,
                                                                      limit,
                                                                      pluginName,
                                                                      withPluginInfo,
                                                                      NULL_PLUGIN_PROPERTIES,
                                                                      AuditLevel.NONE,
                                                                      requestOptions);

offset = 0
limit = 100

payment_method.find_in_batches(offset,
                               limit,
                               options)

paymentMethodApi = killbill.api.PaymentMethodApi()

paymentMethodApi.get_payment_methods(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey": "coolPaymentMethod",
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault": false,
    "pluginName": "__EXTERNAL_PAYMENT__",
    "pluginInfo": null,
    "auditLogs": []
  },
  {
    "paymentMethodId": "dc89832d-18a3-42fd-b3be-cac074fddb36",
    "externalKey": "paypal",
    "accountId": "ca15adc4-1061-4e54-a9a0-15e773b3b154",
    "isDefault": false,
    "pluginName": "killbill-paypal-express",
    "pluginInfo": null,
    "auditLogs": []
  }
]

//First element of the list
class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@3b058e2d
    paymentMethodId: 98420efb-142f-4437-9a93-817ded413313
    externalKey: e78ae144-8727-46f4-8cf2-63636813f232
    accountId: 73f59eee-abec-4d3f-ab62-21dba663bd25
    isDefault: true
    pluginName: noop
    pluginInfo: null
    auditLogs: []
}

[
  {
     "paymentMethodId":"6a0bf13e-d57f-4f79-84bd-3690135f1923",
     "externalKey":"unknown",
     "accountId":"f9c4801f-0daa-4c46-bea0-59490d07fc5e",
     "isDefault":false,
     "pluginName":"__EXTERNAL_PAYMENT__",
     "pluginInfo":{
        "properties":[]
     },
     "auditLogs":[]
  }
]

[{'account_id': '5d82791d-c47f-4c4b-be11-b68233656b96',
 'audit_logs': [],
 'external_key': 'unknown',
 'is_default': False,
 'payment_method_id': '06955087-e191-4da5-99c9-e712b21f6aa6',
 'plugin_info': None,
 'plugin_name': '__EXTERNAL_PAYMENT__'}]

Query Parameters

Name	Type	Required	Default	Description
offset	long	no	0	Starting position in list
limit	long	no	100	Max number of items to return
withPluginInfo	boolean	no	false	If true, include plugin info
pluginName	string	no	all plugins	If present, list only payment methods that use this plugin
pluginProperties	array of strings	no	no properties	return these properties for this plugin
audit	string	no	"NONE"	Level of audit information to return

If withPluginInfo is set to true, attributes for each payment method's plugin are returned. These are plugin-dependent (see discussion above). If pluginName is given, list only payment methods that use this plugin, and return only the attributes specified by pluginProperties. Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Search payment methods

This API searches all payment methods for a specified search string. The search string is given as a path parameter.

HTTP Request

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

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/paymentMethods/search/coolPaymentMethod' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

String searchKey = "4365";
Long offset = 0L;
Long limit = 100L;
String pluginName = null;
Boolean withPluginInfo = true;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

List<PaymentMethod> results = paymentMethodApi.searchPaymentMethods(searchKey, 
                                                                    offset, 
                                                                    limit, 
                                                                    pluginName, 
                                                                    withPluginInfo, 
                                                                    NULL_PLUGIN_PROPERTIES,  
                                                                    AuditLevel.NONE,  
                                                                    requestOptions);

search_key = 'example'
offset = 0
limit = 100

payment_method.find_in_batches_by_search_key(search_key,
                                             offset,
                                             limit,
                                             options)

paymentMethodApi = killbill.api.PaymentMethodApi()
search_key = '__EXTERNAL_PAYMENT__'

paymentMethodApi.search_payment_methods(search_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "externalKey": "coolPaymentMethod",
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "isDefault": false,
    "pluginName": "__EXTERNAL_PAYMENT__",
    "pluginInfo": null,
    "auditLogs": []
  }
]

//First element of the list
class PaymentMethod {
    org.killbill.billing.client.model.gen.PaymentMethod@6b40b41a
    paymentMethodId: 62c434f7-41fe-497d-8fb0-c35bb6706180
    externalKey: 4ac4162a-ae9c-48ca-bb43-8a4bcd6c2717
    accountId: a6941a79-8b7b-4da7-99e0-bffc3d549f87
    isDefault: true
    pluginName: noop
    pluginInfo: class PaymentMethodPluginDetail {
        externalPaymentMethodId: 9ddcce2d-b65f-4e08-8006-1395e47ba97a
        isDefaultPaymentMethod: false
        properties: [class PluginProperty {
            key: CC_NAME
            value: Bozo
            isUpdatable: false
        }, class PluginProperty {
            key: CC_CITY
            value: SF
            isUpdatable: false
        }, class PluginProperty {
            key: CC_LAST_4
            value: 4365
            isUpdatable: false
        }, class PluginProperty {
            key: CC_STATE
            value: CA
            isUpdatable: false
        }, class PluginProperty {
            key: CC_COUNTRY
            value: Zimbawe
            isUpdatable: false
        }]
    }
    auditLogs: []
}

[
  {
     "paymentMethodId":"6a0bf13e-d57f-4f79-84bd-3690135f1923",
     "externalKey":"unknown",
     "accountId":"f9c4801f-0daa-4c46-bea0-59490d07fc5e",
     "isDefault":false,
     "pluginName":"__EXTERNAL_PAYMENT__",
     "pluginInfo":{
        "properties":[]
     },
     "auditLogs":[]
  }
]

[{'account_id': '81d8b04d-dee1-49bf-bc73-48219df21af9',
 'audit_logs': [],
 'external_key': 'unknown',
 'is_default': False,
 'payment_method_id': 'bcecaf3f-16c7-4d65-aed0-b08cc5e34a6b',
 'plugin_info': None,
 'plugin_name': '__EXTERNAL_PAYMENT__'}]

Query Parameters

Name	Type	Required	Default	Description
offset	long	no	0	Starting position in list
limit	long	no	100	Max number of items to return
withPluginInfo	boolean	no	false	If true, include plugin info
pluginName	string	no	all plugins	If present, list only payment methods that use this plugin
pluginProperties	array of strings	no	no properties	return these properties for this plugin
audit	string	no	"NONE"	Level of audit information to return

If withPluginInfo is set to true, attributes for each payment method's plugin are returned. These are plugin-dependent (see discussion above). If pluginName is given, list only payment methods that use this plugin, and return only the attributes specified by pluginProperties. Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list of payment method resource objects that match the search key.

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resources. For more on custom fields see Custom Fields. These endpoints manage custom fields associated with PaymentMethod objects.

Add custom fields to a payment method

Adds one or more custom fields to a payment method object. Existing custom fields are not disturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "objectId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
            "objectType": "PAYMENT_METHOD",
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

paymentMethodApi.createPaymentMethodCustomFields(paymentMethodId, 
                                                 customFields, 
                                                 requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'PAYMENT_METHOD'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

payment_method.add_custom_field(custom_field, 
                                user,
                                reason,
                                comment,
                                options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
body = CustomField(name='Test Custom Field', value='test_value')

paymentMethodApi.create_payment_method_custom_fields(payment_method_id,
                                                     [body],
                                                     created_by,
                                                     api_key,
                                                     api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 3c449da6-7ec4-4c74-813f-f5055739a0b9
    objectType: PAYMENT_METHOD
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"PAYMENT_METHOD",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

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 payment method.

Retrieve payment method custom fields

Returns any custom field objects associated with the specified payment method

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

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/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

List<CustomField> customFields = paymentMethodApi.getPaymentMethodCustomFields(paymentMethodId,
                                                                               AuditLevel.NONE,
                                                                               requestOptions);

audit = 'NONE'

payment_method.custom_fields(audit, options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'

paymentMethodApi.get_payment_method_custom_fields(payment_method_id, 
                                                  api_key, 
                                                  api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f",
    "objectId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "objectType": "PAYMENT_METHOD",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 3c449da6-7ec4-4c74-813f-f5055739a0b9
    objectType: PAYMENT_METHOD
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"PAYMENT_METHOD",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '5670b594-9317-4aeb-bfef-2c2342ec172a',
 'name': 'Test Custom Field',
 'object_id': '4927c1a2-3959-4f71-98e7-ce3ba19c92ac',
 'object_type': 'PAYMENT_METHOD',
 'value': 'test_value'}]

Query Parameters

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

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for payment method

Modifies the value of one or more existing custom fields associated with a payment object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "customFieldId": "6d4c073b-fd89-4e39-9802-eba65f42492f",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/customFields' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");

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);
paymentMethodApi.modifyPaymentMethodCustomFields(paymentMethodId, 
                                                 customFields, 
                                                 requestOptions);

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

payment_method.modify_custom_field(custom_field,                                                                                            
                                   user, 
                                   reason,
                                   comment, 
                                   options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
body = CustomField(custom_field_id=custom_field_id, 
                   name='Test Custom Field', 
                   value='test_value')

paymentMethodApi.modify_payment_method_custom_fields(payment_method_id, 
                                                     [body], 
                                                     created_by, 
                                                     api_key, 
                                                     api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

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.

Response

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

Remove custom fields from payment method

Delete one or more custom fields from a payment method

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/paymentMethods/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=439ed0f8-9b37-4688-bace-e2595b1d3801' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("3c449da6-7ec4-4c74-813f-f5055739a0b9");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = ImmutableList.<UUID>of(customFieldsId);
paymentMethodApi.deletePaymentMethodCustomFields(paymentMethodId, 
                                                 customFieldsList, 
                                                 requestOptions);

custom_field_id = custom_field.id

payment_method.remove_custom_field(custom_field_id,                                                                                            
                                   user, 
                                   reason,
                                   comment, 
                                   options)

paymentMethodApi = killbill.api.PaymentMethodApi()
payment_method_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'

paymentMethodApi.delete_payment_method_custom_fields(payment_method_id,
                                                     created_by,
                                                     api_key, 
                                                     api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	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.

Audit Logs

This endpoint enables access to payment method audit logs. For more on audit logs see the Audit and History section under Using Kill Bill APIs.

Retrieve payment method audit logs with history by id

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentMethods/{paymentMethodId}/auditLogsWithHistory

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/paymentMethods/916619a4-02bb-4d3d-b3da-2584ac897b19/auditLogsWithHistory' 

import org.killbill.billing.client.api.gen.PaymentMethodApi;
protected PaymentMethodApi paymentMethodApi;

UUID paymentMethodId = UUID.fromString("e9d95f16-a426-46d0-b76b-90814792fb36");

List<AuditLog> result = paymentMethodApi.getPaymentMethodAuditLogsWithHistory(paymentMethodId, requestOptions);

accountApi = killbill.api.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'
account_email_id = 'bb390282-6757-4f4f-8dd5-456abd9f30b2'

accountApi.get_account_email_audit_logs_with_history(account_id,
                                                     account_email_id,
                                                     api_key,
                                                     api_secret)

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

account.email_audit_logs_with_history(account_email_id, options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-19T14:56:07.000Z",
    "objectType": "PAYMENT_METHOD",
    "objectId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "f77892e9-32bd-4d59-8039-5e12798b53fe",
    "history": 
    {
      "id": null,
      "createdDate": "2018-07-19T14:56:07.000Z",
      "updatedDate": "2018-07-19T14:56:07.000Z",
      "recordId": 10,
      "accountRecordId": 35,
      "tenantRecordId": 1,
      "externalKey": "unknown",
      "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
      "pluginName": "__EXTERNAL_PAYMENT__",
      "isActive": true,
      "active": true,
      "tableName": "PAYMENT_METHODS",
      "historyTableName": "PAYMENT_METHOD_HISTORY"
    }
  }
]

//First element of the list
class AuditLog {
    changeType: INSERT
    changeDate: 2012-08-25T00:00:03.000Z
    objectType: PAYMENT_METHOD
    objectId: e9d95f16-a426-46d0-b76b-90814792fb36
    changedBy: Toto
    reasonCode: i am god
    comments: no comment
    userToken: 081ae8a2-b267-4808-8ae9-eb60f4e5a2d5
    history: {id=null, 
              createdDate=2012-08-25T00:00:03.000Z, 
              updatedDate=2012-08-25T00:00:03.000Z, 
              recordId=1, 
              accountRecordId=1, 
              tenantRecordId=1, 
              externalKey=85905d6e-64d6-4ac9-85d5-0ce45d37a426, 
              accountId=58780aff-a193-4544-9f82-6b3d91b040ac, 
              pluginName=noop, 
              isActive=true, 
              active=true, 
              tableName=PAYMENT_METHODS, 
              historyTableName=PAYMENT_METHOD_HISTORY}
}

[
   {
      "changeType":"INSERT",
      "changeDate":"2013-08-01T06:00:00.000Z",
      "objectType":"ACCOUNT_EMAIL",
      "objectId":"a4627e89-a73b-4167-a7ba-92a2881eb3c4",
      "changedBy":"test_account_tags",
      "userToken":"79005abf-a8cf-44e1-84fc-945381d35bd5",
      "history":{
         "id":null,
         "createdDate":"2013-08-01T06:00:00.000Z",
         "updatedDate":"2013-08-01T06:00:00.000Z",
         "recordId":18,
         "accountRecordId":525,
         "tenantRecordId":842,
         "accountId":"1ced5fc2-b032-4969-a38b-d4db9ab5368f",
         "email":"email@laposte.com",
         "isActive":true,
         "tableName":"ACCOUNT_EMAIL",
         "historyTableName":"ACCOUNT_EMAIL_HISTORY"
      }
   }
]

[{'change_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc()),
 'change_type': 'INSERT',
 'changed_by': 'Me',
 'comments': None,
 'history': {'created_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc()),
             'id': None,
             'updated_date': datetime.datetime(2018, 5, 23, 16, 7, 1, tzinfo=tzutc())},
 'object_id': 'bb390282-6757-4f4f-8dd5-456abd9f30b2',
 'object_type': 'ACCOUNT_EMAIL',
 'reason_code': None,
 'user_token': '548055b7-2c5e-4315-9293-d76c00bd9737'}]

Query Parameters

None.

Returns

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

Subscription

A Subscription in Kill Bill entitles a customer to the use of a product or service for a period of time in exchange for a specified payment. Every subscription belongs to a Bundle that is associated with a given customer Account.

Subscriptions are created by specifying a Plan from the catalog, and an effective date on which to start. The Plan identifies the Product subscribed along with the terms of service and of billing. These attributes are used by the system to drive the generation of invoices. Kill Bill offers two parallel views of the subscription: one to track the entitlement, i.e the service associated with the subscription, and one to track the billing. These views address the following questions:

• Given a date, how much should we invoice ?
• Given a date, is the service available to the customer?

For most use cases, those two views are one and the same; the customer gets invoiced for what she consumes.

Please refer to our subscription manual for more details.

Subscription Resource

The Subscription resource represents a subscription. The attributes contained in the subscription resource are the following:

Name	Type	Generated by	Description
accountId	string	system	UUID for the account
bundleId	string	system	UUID for the bundle
subscriptionId	string	system	UUID for this subscription
externalKey	string	user	Optional external key for the subscription
bundleExternalKey	string	user	Optional external key for the bundle
startDate	date	user	The date the service (entitlement) starts
productName	string	user	Name of the product subscribed (from catalog)
productCategory	string	user	Product catgory (see notes below)
billingPeriod	string	user	Billing period (see notes below)
phaseType	string	user	Type of the current plan phase (see notes below)
priceList	string	user	Name of the current price list (from catalog)
planName	string	user	Name of the current plan (from catalog)
state	string	system	Current state of the subscription (see notes below)
sourceType	string	system	Kind of subscription (see notes below)
cancelledDate	date	user	Date when the service stopped, or will stop
chargedThroughDate	date	system	Date up to which the subscription has been invoiced (see notes below)
billingStartDate	date	user	Date on which the system starts invoicing
billingEndDate	date	user	Date on which the system ends invoicing
billCycleDayLocal	integer	user or system	Day of the month on which invoices are generated, if applicable (see notes below)
events	list	system	list of subscription events tracking what happened (see notes below)
price	list	user	list of prices, one for each phase in the plan
priceOverrides	list	user	list of prices if this subscription has price overrides

productCategory: possible values are BASE, ADD_ON, or STANDALONE

billingPeriod: possible values are DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, SIXTY_DAYS, NINETY_DAYS, MONTHLY, BIMESTRIAL (bimonthly), QUARTERLY, TRIANNUAL, BIANNUAL, ANNUAL, BIENNIAL, or NO_BILLING_PERIOD

phaseType: possible values are: TRIAL, DISCOUNT, FIXEDTERM, or EVERGREEN

state: possible values are:

• PENDING: The subscription is not yet created.
• ACTIVE: The subscription is currently active.
• BLOCKED: The subscription is currently paused.
• CANCELLED: The subscription has been cancelled.

sourceType: possible values are NATIVE, MIGRATED, or TRANSFERRED

chargedThroughDate: The date up to which the entitlement for this subscription has been invoiced. For IN_ADVANCE billing mode, this date will often be in the future; for IN_ARREAR, this date will often be in the past. For example,

1. A subscription is billed each month, on the 15th, in advance. If we check on May 31, the chargedThroughDate will be June 15th, 15 days ahead. If the subscription is ended on May 31, a prorated credit will need to be issued.

2. A subscription is billed quarterly, in arrears, on the 10th of Feb., May, Aug., and Nov. If we check on Jul. 20, the chargedThroughDate will be May 10, over 2 months earlier. If the subscription is cancelled on Jul. 20, an additional invoice will need to be issued.

These use cases assume that invoicing is up to date. If AUTO_INVOICING_OFF is set, invoicing relies on a manual process and may be late. In that situation the first use case may require a smaller credit or none at all, while the second case will have a larger amount to be billed to close out the subscription.

billCycleDayLocal: this value is either the overridden subscription billCycleDay (in case of BCD change) or the value at the subscription, bundle or account level (depending on the catalog billing alignments). For ACCOUNT billing alignments, if the account level billCycleDay hasn't been set yet, the value returned would be null.

Events: possible event types are START_ENTITLEMENT, START_BILLING, PAUSE_ENTITLEMENT, PAUSE_BILLING, RESUME_ENTITLEMENT, RESUME_BILLING, PHASE, CHANGE, STOP_ENTITLEMENT, STOP_BILLING, SERVICE_STATE_CHANGE

Subscriptions

These endpoints support the basic CRUD operations on Subscriptions.

Create a subscription

This API creates a base product subscription. It also creates a bundle to contain the subscription. See Bundle for further information.

HTTP Request

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

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 "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
            "externalKey": "somethingSpecial",
            "planName": "super-monthly"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions" 

    OR

    curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
          "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
            "externalKey": "somethingSpecial", 
            "productName": "Test", 
            "productCategory": "BASE",  
            "billingPeriod": "MONTHLY",
            "priceList": "DEFAULT"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions"    

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID accountId = UUID.fromString("905a0636-ab63-40c0-acd4-b461b6808b5d");

Subscription input = new Subscription();
input.setAccountId(accountId);
input.setExternalKey("somethingSpecial");
input.setPlanName("shotgun-monthly");

LocalDate entitlementDate = null;
LocalDate billingDate = null;
Boolean renameKeyIfExistsAndUnused = null; 
Boolean migrated = null;
Boolean callCompletion = true;
long DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC = 10;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Subscription subscription = subscriptionApi.createSubscription(input, 
                                                               entitlementDate, 
                                                               billingDate, 
                                                               renameKeyIfExistsAndUnused, 
                                                               migrated, 
                                                               callCompletion, 
                                                               DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC, 
                                                               NULL_PLUGIN_PROPERTIES, 
                                                               requestOptions);

subscription              = KillBillClient::Model::Subscription.new
subscription.account_id   = "e1826665-4524-4d57-81b5-a5eb11146f3f"
subscription.plan_name    = "basic-monthly-in-advance"

requested_date  = nil
call_completion = nil 

subscription.create(user, 
                    reason, 
                    comment, 
                    requested_date, 
                    call_completion, 
                    options)

subscriptionApi = killbill.api.SubscriptionApi()
account_id = 'e1826665-4524-4d57-81b5-a5eb11146f3f'
body = Subscription(account_id=account_id, plan_name='standard-monthly')

subscriptionApi.create_subscription(body,
                                    created_by,
                                    api_key,
                                    api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712
< Content-Type: application/json
< Content-Length: 0

class Subscription {
    org.killbill.billing.client.model.gen.Subscription@49563466
    accountId: e8cd6795-0da1-4848-831f-51977eed42b1
    bundleId: eac6eecf-2060-434a-b472-170f80a7591c
    subscriptionId: a74081ee-d7bb-4387-a1df-34e962e37699
    externalKey: somethingSpecial
    bundleExternalKey: somethingAlsoSpecial
    startDate: 2012-04-25
    productName: Shotgun
    productCategory: BASE
    billingPeriod: MONTHLY
    phaseType: TRIAL
    priceList: DEFAULT
    planName: shotgun-monthly
    state: ACTIVE
    sourceType: NATIVE
    cancelledDate: null
    chargedThroughDate: null
    billingStartDate: 2012-04-25
    billingEndDate: null
    billCycleDayLocal: 25
    events: [class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@37b70727
        eventId: 9ef798a3-95f6-41ac-9b86-00c9385c155f
        billingPeriod: MONTHLY
        effectiveDate: 2012-04-25
        plan: shotgun-monthly
        product: Shotgun
        priceList: DEFAULT
        eventType: START_ENTITLEMENT
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: entitlement-service
        serviceStateName: ENT_STARTED
        phase: shotgun-monthly-trial
        auditLogs: []
    }, class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@410923f5
        eventId: 65ec07fa-61c7-4f05-bd6f-82cea23cf06a
        billingPeriod: MONTHLY
        effectiveDate: 2012-04-25
        plan: shotgun-monthly
        product: Shotgun
        priceList: DEFAULT
        eventType: START_BILLING
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: billing-service
        serviceStateName: START_BILLING
        phase: shotgun-monthly-trial
        auditLogs: []
    }, class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@cac84db3
        eventId: 88f77a50-edca-4cc3-b234-5d70c457128c
        billingPeriod: MONTHLY
        effectiveDate: 2012-05-25
        plan: shotgun-monthly
        product: Shotgun
        priceList: DEFAULT
        eventType: PHASE
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: entitlement+billing-service
        serviceStateName: PHASE
        phase: shotgun-monthly-evergreen
        auditLogs: []
    }]
    priceOverrides: null
    prices: [class PhasePrice {
        planName: shotgun-monthly
        phaseName: shotgun-monthly-trial
        phaseType: TRIAL
        fixedPrice: 0
        recurringPrice: null
        usagePrices: []
    }, class PhasePrice {
        planName: shotgun-monthly
        phaseName: shotgun-monthly-evergreen
        phaseType: EVERGREEN
        fixedPrice: null
        recurringPrice: 249.95
        usagePrices: []
    }]
    auditLogs: []
}

{
   "accountId":"e1826665-4524-4d57-81b5-a5eb11146f3f",
   "bundleId":"f3dea847-1567-467a-8373-838dfdcf6afc",
   "subscriptionId":"ee508b5b-46b8-42a7-8988-16c0470de4ae",
   "externalKey":"f3dea847-1567-467a-8373-838dfdcf6afc",
   "bundleExternalKey":"addea847-1467-167a-1373-988dfdcf7acc",
   "startDate":"2013-08-01",
   "productName":"Basic",
   "productCategory":"BASE",
   "billingPeriod":"MONTHLY",
   "phaseType":"EVERGREEN",
   "priceList":"DEFAULT",
   "planName":"basic-monthly-in-advance",
   "state":"ACTIVE",
   "sourceType":"NATIVE",
   "chargedThroughDate":"2013-09-01",
   "billingStartDate":"2013-08-01",
   "billCycleDayLocal":1,
   "events":[
      {
         "eventId":"341fc529-612b-4bb9-b8d7-ee4a9115f577",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_ENTITLEMENT",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement-service",
         "serviceStateName":"ENT_STARTED",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      },
      {
         "eventId":"caa54161-c001-44a0-9ff0-80be59989380",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_BILLING",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"billing-service",
         "serviceStateName":"START_BILLING",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      }
   ],
   "prices":[
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"asic-monthly-in-advance-trial",
         "phaseType":"TRIAL",
         "fixedPrice":0,
         "recurringPrice":null,
         "usagePrices":[]
      },
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"basic-monthly-in-advance-evergreen",
         "phaseType":"EVERGREEN",
         "fixedPrice":null,
         "recurringPrice":500.0,
         "usagePrices":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A subscription resource object specifying accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

It can also include the following optional fields:

• phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
• externalKey - External key corresponding to the subscription.
• billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
• bundleId - Id of the bundle in which to create this subscription. Can be specified only while invoking this method for an addon subscription.

Query Parameters

Name	Type	Required	Default	Description
entitlementDate	string	no	immediately	Date at which the entitlement (service) starts in yyyy-mm-dd format.
billingDate	string	no	immediately	Date at which the billing starts in yyyy-mm-dd format.
renameKeyIfExistsAndUnused	boolean	no	true	If true, rename external key if it exists and is unused
migrated	boolean	no	false	If true, subscription is migrated
callCompletion	boolean	no	false	see below
callTimeoutSec	long	no	unlimited?	Timeout in seconds (see below)

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Other Notes The entitlementDate drives the subscription state. So, if a subscription is created with a future entitlementDate, its state remains PENDING until the date is reached after which it becomes ACTIVE.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location parameter is returned in the header which contains the new subscription id.

Create a subscription with addon products

This API creates an addon product subscription. The bundle for the base subscription must be specified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns

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 "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
            "externalKey": "something",
            "bundleExternalKey": "somethingAlso",
            "productName": "Sports",
            "productCategory": "BASE",
            "billingPeriod": "MONTHLY",
            "priceList": "DEFAULT"
        },
        {
          "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
          "productName": "OilSlick",
          "productCategory": "ADD_ON",
          "billingPeriod": "MONTHLY",
          "priceList": "DEFAULT"
        }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns' 

OR

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[

        {
          "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
          "planName": "remotecontrol-monthly",
          "bundleId":"b4709feb-bd14-455a-bbb4-57a758498791"
        }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns'   

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID accountId = UUID.fromString("abfba40d-d2dd-47f0-94f2-8ea3e6bc8794");

Subscription base = new Subscription();
base.setAccountId(accountId);
base.setExternalKey("base");
base.setProductName("Shotgun");
base.setProductCategory(ProductCategory.BASE);
base.setBillingPeriod(BillingPeriod.MONTHLY);
base.setPriceList("DEFAULT");

final Subscription addOn1 = new Subscription();
addOn1.setAccountId(accountId);
addOn1.setProductName("Telescopic-Scope");
addOn1.setProductCategory(ProductCategory.ADD_ON);
addOn1.setBillingPeriod(BillingPeriod.MONTHLY);
addOn1.setPriceList("DEFAULT");

final Subscription addOn2 = new Subscription();
addOn2.setAccountId(accountId);
addOn2.setProductName("Laser-Scope");
addOn2.setProductCategory(ProductCategory.ADD_ON);
addOn2.setBillingPeriod(BillingPeriod.MONTHLY);
addOn2.setPriceList("DEFAULT");

final Subscriptions subscriptions = new Subscriptions();
subscriptions.add(base);
subscriptions.add(addOn1);
subscriptions.add(addOn2);

LocalDate entitlementDate = null;
LocalDate billingDate = null;
Boolean migrated = null;
Boolean renameKeyIfExistsAndUnused = null;
Boolean callCompletion = true;
long DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC = 10;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

final Bundle bundle = subscriptionApi.createSubscriptionWithAddOns(subscriptions, 
                                                                   entitlementDate, 
                                                                   billingDate, 
                                                                   migrated, 
                                                                   renameKeyIfExistsAndUnused, 
                                                                   callCompletion, 
                                                                   DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC, 
                                                                   NULL_PLUGIN_PROPERTIES, 
                                                                   requestOptions);

entitlement = [
                 {
                    "baseEntitlementAndAddOns":[
                       {
                          "accountId":"16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836",
                          "externalKey":"1-16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836-827963",
                          "productCategory":"BASE",
                          "planName":"sports-monthly"
                       }
                    ]
                 }
              ]
requested_date = nil
entitlement_date = nil
billing_date = nil
migrated = false
call_completion_sec = 3

subscription = KillBillClient::Model::Subscription.new
subscription.create_entitlement_with_add_on(entitlement,
                                            requested_date,
                                            entitlement_date, 
                                            billing_date,
                                            migrated, 
                                            call_completion_sec,                                            
                                            user, 
                                            reason, 
                                            comment, 
                                            options)                                         

subscriptionApi = killbill.api.SubscriptionApi()
account_id = '16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836'
subscription_a = Subscription(account_id=account_id,
                              product_category='BASE',
                              plan_name='sports-monthly')

subscription_b = Subscription(account_id=account_id,
                              product_category='ADD_ON',
                              plan_name='super-monthly')

body = [subscription_a, subscription_b]

subscriptionApi.create_subscription_with_add_ons(body,
                                                 created_by,
                                                 api_key,
                                                 api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/accounts/886adb60-be70-40c8-b97d-1f8ecbc30a64/bundles?bundlesFilter=cbcc7642-1aa5-4609-b89d-5356d05819be
< Content-Type: application/json
< Content-Length: 0

class Bundle {
    org.killbill.billing.client.model.gen.Bundle@ddd846f9
    accountId: abfba40d-d2dd-47f0-94f2-8ea3e6bc8794
    bundleId: 83f3a7b5-63c9-4b06-a1f5-7140fec67558
    externalKey: base
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@bb1bf160
        accountId: abfba40d-d2dd-47f0-94f2-8ea3e6bc8794
        bundleId: 83f3a7b5-63c9-4b06-a1f5-7140fec67558
        subscriptionId: 6fcf439b-4198-4963-8f0e-7e3054525a24
        externalKey: base
        startDate: 2012-04-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-04-25
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a6789138
            eventId: fb7d653a-cadb-46f6-a04f-dbe7043385ed
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@b4b456ed
            eventId: b5c00fdf-6ce4-46ad-b996-5513146d8acd
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@fb1cc392
            eventId: edd91628-323d-4a3a-b07e-bef09a2623a2
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePrices: []
        }, class PhasePrice {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePrices: []
        }]
        auditLogs: []
    }, class Subscription {
        org.killbill.billing.client.model.gen.Subscription@37a59f88
        accountId: abfba40d-d2dd-47f0-94f2-8ea3e6bc8794
        bundleId: 83f3a7b5-63c9-4b06-a1f5-7140fec67558
        subscriptionId: a490a1c8-ca78-4cbd-bb5a-1ce214cc2f23
        externalKey: base
        startDate: 2012-04-25
        productName: Telescopic-Scope
        productCategory: ADD_ON
        billingPeriod: MONTHLY
        phaseType: DISCOUNT
        priceList: DEFAULT
        planName: telescopic-scope-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-05-25
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@9c41861a
            eventId: 6be47e8c-0ff6-45ee-9b79-7a91c6867e6c
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: telescopic-scope-monthly
            product: Telescopic-Scope
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: telescopic-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a386d43d
            eventId: 0c6b12cb-9390-4d64-b98a-93a8c9a6b67b
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: telescopic-scope-monthly
            product: Telescopic-Scope
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: telescopic-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@429a9148
            eventId: 27ce7282-c84c-495a-a7fc-be393cfcf3a7
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: telescopic-scope-monthly
            product: Telescopic-Scope
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: telescopic-scope-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: telescopic-scope-monthly
            phaseName: telescopic-scope-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePrices: []
        }, class PhasePrice {
            planName: telescopic-scope-monthly
            phaseName: telescopic-scope-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePrices: []
        }]
        auditLogs: []
    }, class Subscription {
        org.killbill.billing.client.model.gen.Subscription@10da5c43
        accountId: abfba40d-d2dd-47f0-94f2-8ea3e6bc8794
        bundleId: 83f3a7b5-63c9-4b06-a1f5-7140fec67558
        subscriptionId: 8f957bfa-61da-45ca-ae4c-ed34b045f18e
        externalKey: base
        startDate: 2012-04-25
        productName: Laser-Scope
        productCategory: ADD_ON
        billingPeriod: MONTHLY
        phaseType: DISCOUNT
        priceList: DEFAULT
        planName: laser-scope-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-05-25
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@6615c622
            eventId: eb05b9d5-a055-426c-8411-7fd9b4728d45
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@41ddb948
            eventId: 6fbe3e71-7e3b-4c3b-8bdd-27c8dc71e044
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@182c6fd0
            eventId: bec40e45-6ffb-49f3-831d-722f19d8ed09
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: laser-scope-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: laser-scope-monthly
            phaseName: laser-scope-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePrices: []
        }, class PhasePrice {
            planName: laser-scope-monthly
            phaseName: laser-scope-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePrices: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@8a202296
        accountId: abfba40d-d2dd-47f0-94f2-8ea3e6bc8794
        bundleId: 83f3a7b5-63c9-4b06-a1f5-7140fec67558
        externalKey: base
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@5aa4f7e9
            eventId: eb05b9d5-a055-426c-8411-7fd9b4728d45
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@1df149f3
            eventId: 6be47e8c-0ff6-45ee-9b79-7a91c6867e6c
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@68a2bc3b
            eventId: fb7d653a-cadb-46f6-a04f-dbe7043385ed
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@787b414d
            eventId: 6fbe3e71-7e3b-4c3b-8bdd-27c8dc71e044
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: laser-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@5ba02249
            eventId: 0c6b12cb-9390-4d64-b98a-93a8c9a6b67b
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: telescopic-scope-monthly
            product: Telescopic-Scope
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: telescopic-scope-monthly-discount
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d45c4b96
            eventId: b5c00fdf-6ce4-46ad-b996-5513146d8acd
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@2360e010
            eventId: bec40e45-6ffb-49f3-831d-722f19d8ed09
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: laser-scope-monthly
            product: Laser-Scope
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: laser-scope-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@49d428fe
            eventId: 27ce7282-c84c-495a-a7fc-be393cfcf3a7
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: telescopic-scope-monthly
            product: Telescopic-Scope
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: telescopic-scope-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@aebff2be
            eventId: edd91628-323d-4a3a-b07e-bef09a2623a2
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

no content

no content

Request Body

A subscription resource object corresponding to the base subscription and zero or more subscription resource objects corresponding to add-on subscriptions need to be specified. Alternatively, only a list of add-on subscription resource objects may be specified along with the base subscription bundle id. Each subscription resource object needs to include accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

In addition, each subscription resource can also include the following optional fields:

• phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
• externalKey - External key corresponding to the subscription.
• billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
• bundleId - Id of the bundle in which to create this subscription. Can be specified only with an add-on subscription resource.

Query Parameters

Name	Type	Required	Default	Description
entitlementDate	string	no	immediately	Date at which the entitlement (sevice) starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
billingDate	string	no	immediately	Date at which the billing starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
renameKeyIfExistsAndUnused	boolean	no	true	If true, rename external key if it exists and is unused
migrated	boolean	no	false	If true, subscription is migrated
callCompletion	boolean	no	false	see below
callTimeoutSec	long	no	unlimited?	Timeout in seconds (see below)

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location parameter is returned in the header which contains the new subscription id.

Create multiple subscriptions with addon products

This API creates multiple subscriptions with addon products. The bundle for the base subscription must be specified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns

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 "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "886adb60-be70-40c8-b97d-1f8ecbc30a64",
                "externalKey": "base",
                "productName": "Sports",
                "productCategory": "BASE",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              },
              {
                "accountId": "886adb60-be70-40c8-b97d-1f8ecbc30a64",
                "productName": "OilSlick",
                "productCategory": "ADD_ON",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              }
            ]
          },
           {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
                "externalKey": "createSubscriptionsWithAddOns3",
                "productName": "Test",
                "productCategory": "BASE",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              },
              {
                "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
                "productName": "TestAO",
                "productCategory": "ADD_ON",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              }
            ]
          }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns' 

OR 

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
                "planName": "remotecontrol-monthly",  
                "bundleId":"a8b4022c-e38c-4336-ad2f-ee15c5e18d12"
              }
            ]
          },
          {
            "baseEntitlementAndAddOns": [

              {
                "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
                "planName": "remotecontrol-monthly",
                "bundleId":"06892885-c276-4cf9-8311-ef0b8a2e364b"
              }
            ]
          }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID accountId = UUID.fromString("a3087bfb-eb81-466d-afeb-6501c30f8f85");

Subscription base = new Subscription();
base.setAccountId(accountId);
base.setPlanName("test-monthly");

final Subscription addOn1 = new Subscription();
addOn1.setAccountId(accountId);
addOn1.setPlanName("testao-monthly");

final Subscriptions subscriptions = new Subscriptions();
subscriptions.add(base);
subscriptions.add(addOn1);

BulkSubscriptionsBundle bulkSubscriptionsBundle = new BulkSubscriptionsBundle();
bulkSubscriptionsBundle.setBaseEntitlementAndAddOns(subscriptions);

Subscription base2 = new Subscription();
base2.setAccountId(accountId);
base2.setPlanName("product1-monthly");

Subscription base2addOn1 = new Subscription();
base2addOn1.setAccountId(accountId);
base2addOn1.setPlanName("product1-ao-monthly");
base2addOn1.setBillCycleDayLocal(18);

Subscriptions subscriptions2 = new Subscriptions();
subscriptions2.add(base2);
subscriptions2.add(base2addOn1);

BulkSubscriptionsBundle bulkSubscriptionsBundle2 = new BulkSubscriptionsBundle();
bulkSubscriptionsBundle2.setBaseEntitlementAndAddOns(subscriptions2);

BulkSubscriptionsBundles bulkSubscriptionsBundles = new BulkSubscriptionsBundles();
bulkSubscriptionsBundles.add(bulkSubscriptionsBundle);
bulkSubscriptionsBundles.add(bulkSubscriptionsBundle2);

LocalDate entitlementDate = null;
LocalDate billingDate = null;
Boolean renameKeyIfExistsAndUnused = false;
Boolean migrated = false;
Boolean callCompletion = true;
long DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC = 10;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Bundles bundles = subscriptionApi.createSubscriptionsWithAddOns(bulkSubscriptionsBundles, 
                                                                 entitlementDate, 
                                                                 billingDate, 
                                                                 renameKeyIfExistsAndUnused, 
                                                                 migrated, 
                                                                 callCompletion, 
                                                                DEFAULT_WAIT_COMPLETION_TIMEOUT_SEC, NULL_PLUGIN_PROPERTIES,                                                               requestOptions);

bulk_subscription_list = [
                            {
                               "baseEntitlementAndAddOns":[
                                  {
                                     "accountId":"16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836",
                                     "externalKey":"1-16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836-827963",
                                     "productCategory":"BASE",
                                     "planName":"sports-monthly"
                                  }
                               ]
                            },
                            {
                               "baseEntitlementAndAddOns":[
                                  {
                                     "accountId":"16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836",
                                     "externalKey":"2-16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836-717751",
                                     "productCategory":"ADD_ON",
                                     "planName":"super-monthly"
                                  }
                               ]
                            }
                         ]
entitlement_date = nil
billing_date = nil
call_completion_sec = nil

KillBillClient::Model::BulkSubscription.create_bulk_subscriptions(bulk_subscription_list, 
                                                                  user, 
                                                                  reason, 
                                                                  comment, 
                                                                  entitlement_date, 
                                                                  billing_date, 
                                                                  call_completion_sec, 
                                                                  options)

subscriptionApi = killbill.api.SubscriptionApi()
account_id = '16cd9eb8-bb5d-4183-b8e0-c1d6f78dc836'
subscription_a = Subscription(account_id=account_id,
                              product_category='BASE',
                              plan_name='sports-monthly')

subscription_b = Subscription(account_id=account_id,
                              product_category='ADD_ON',
                              plan_name='super-monthly')

body = BulkSubscriptionsBundle([subscription_a, subscription_b])

subscriptionApi.create_subscriptions_with_add_ons([body],
                                                  created_by,
                                                  api_key,
                                                  api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/accounts/886adb60-be70-40c8-b97d-1f8ecbc30a64/bundles?bundlesFilter=cbcc7642-1aa5-4609-b89d-5356d05819be
< Content-Type: application/json
< Content-Length: 0

class Bundle {
    org.killbill.billing.client.model.gen.Bundle@ccb83609
    accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
    bundleId: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
    externalKey: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@6ab8272b
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        bundleExternalKey: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        subscriptionId: 266ff081-db2a-4fd9-b9b4-4a4b85c553df
        externalKey: 266ff081-db2a-4fd9-b9b4-4a4b85c553df
        startDate: 2021-11-29
        productName: Product1
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: product1-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2021-11-29
        billingStartDate: 2021-11-29
        billingEndDate: null
        billCycleDayLocal: 29
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@9ac9be06
            eventId: 12c85188-f2a8-4590-83af-65c75fc9677b
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-monthly
            product: Product1
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: product1-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@546fe023
            eventId: eadcaf35-673e-4d93-8adf-dfe5ad6422cb
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-monthly
            product: Product1
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: product1-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@37f33629
            eventId: 29a3ccee-f331-48d4-b1c6-be7f03d0d8c5
            billingPeriod: MONTHLY
            effectiveDate: 2021-12-09
            plan: product1-monthly
            product: Product1
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: product1-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: product1-monthly
            phaseName: product1-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePrices: []
        }, class PhasePrice {
            planName: product1-monthly
            phaseName: product1-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 10
            usagePrices: []
        }]
        auditLogs: []
    }, class Subscription {
        org.killbill.billing.client.model.gen.Subscription@edd6cbe2
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        bundleExternalKey: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        subscriptionId: 244d5e5a-71af-4bfc-b7ec-7651f30e7208
        externalKey: 244d5e5a-71af-4bfc-b7ec-7651f30e7208
        startDate: 2021-11-29
        productName: product1-ao
        productCategory: ADD_ON
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: product1-ao-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2021-11-29
        billingStartDate: 2021-11-29
        billingEndDate: null
        billCycleDayLocal: 18
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@13fb439a
            eventId: 8a9c0292-a36d-4428-ac47-c9fe39876d5a
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: product1-ao-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@8553fc75
            eventId: 6c87c127-edef-4762-9804-3cd8638673be
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: product1-ao-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@28e2d33d
            eventId: 13495761-2cf0-46aa-ab80-7586cdaf8a11
            billingPeriod: MONTHLY
            effectiveDate: 2021-12-09
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: product1-ao-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: product1-ao-monthly
            phaseName: product1-ao-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePrices: []
        }, class PhasePrice {
            planName: product1-ao-monthly
            phaseName: product1-ao-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 5
            usagePrices: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@26b7a071
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        externalKey: 18cae774-d466-4a19-b1d3-d64fb6c0bd30
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d4de5a4
            eventId: 8a9c0292-a36d-4428-ac47-c9fe39876d5a
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: product1-ao-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@6312065e
            eventId: 12c85188-f2a8-4590-83af-65c75fc9677b
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: product1-ao-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a057c269
            eventId: 6c87c127-edef-4762-9804-3cd8638673be
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: product1-ao-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@535f32e2
            eventId: eadcaf35-673e-4d93-8adf-dfe5ad6422cb
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: product1-monthly
            product: Product1
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: product1-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d0d4bb9c
            eventId: 13495761-2cf0-46aa-ab80-7586cdaf8a11
            billingPeriod: MONTHLY
            effectiveDate: 2021-12-09
            plan: product1-ao-monthly
            product: product1-ao
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: product1-ao-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@8351e73e
            eventId: 29a3ccee-f331-48d4-b1c6-be7f03d0d8c5
            billingPeriod: MONTHLY
            effectiveDate: 2021-12-09
            plan: product1-monthly
            product: Product1
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: product1-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}, class Bundle {
    org.killbill.billing.client.model.gen.Bundle@2fedb607
    accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
    bundleId: 64123897-ae99-452b-9dbd-88dd9f591bf4
    externalKey: 64123897-ae99-452b-9dbd-88dd9f591bf4
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@39c20f59
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 64123897-ae99-452b-9dbd-88dd9f591bf4
        bundleExternalKey: 64123897-ae99-452b-9dbd-88dd9f591bf4
        subscriptionId: ccbb17ab-0734-49be-8a2a-ccc3fbe2ecdf
        externalKey: ccbb17ab-0734-49be-8a2a-ccc3fbe2ecdf
        startDate: 2021-11-29
        productName: Test
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: EVERGREEN
        priceList: DEFAULT
        planName: test-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2021-12-29
        billingStartDate: 2021-11-29
        billingEndDate: null
        billCycleDayLocal: 29
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@1bb29bcf
            eventId: 133ae9b4-a250-4d93-8919-534a990ed4e4
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: test-monthly
            product: Test
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: test-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@f46f814d
            eventId: 309cc4d6-c21e-4e01-8289-a5767e8272e8
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: test-monthly
            product: Test
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: test-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: test-monthly
            phaseName: test-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 20
            usagePrices: []
        }]
        auditLogs: []
    }, class Subscription {
        org.killbill.billing.client.model.gen.Subscription@c984106f
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 64123897-ae99-452b-9dbd-88dd9f591bf4
        bundleExternalKey: 64123897-ae99-452b-9dbd-88dd9f591bf4
        subscriptionId: 15e08a0d-9cce-4eb6-b3ce-ecd42e82ffa0
        externalKey: 15e08a0d-9cce-4eb6-b3ce-ecd42e82ffa0
        startDate: 2021-11-29
        productName: TestAO
        productCategory: ADD_ON
        billingPeriod: MONTHLY
        phaseType: EVERGREEN
        priceList: DEFAULT
        planName: testao-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2021-12-29
        billingStartDate: 2021-11-29
        billingEndDate: null
        billCycleDayLocal: 29
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d1b77a46
            eventId: 02dcf5bd-a284-47ef-b88a-a5d8a67ba14c
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: testao-monthly
            product: TestAO
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: testao-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@997747ea
            eventId: b724dc1a-e6bc-4a09-8790-f1d1d81bb8b5
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: testao-monthly
            product: TestAO
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: testao-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: null
        prices: [class PhasePrice {
            planName: testao-monthly
            phaseName: testao-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: 100
            recurringPrice: 10
            usagePrices: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@379f0209
        accountId: 1d6ef148-3e91-455d-937a-27d8b2f6deff
        bundleId: 64123897-ae99-452b-9dbd-88dd9f591bf4
        externalKey: 64123897-ae99-452b-9dbd-88dd9f591bf4
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@7ebf20b
            eventId: 02dcf5bd-a284-47ef-b88a-a5d8a67ba14c
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: test-monthly
            product: Test
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: test-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d60a18b
            eventId: 133ae9b4-a250-4d93-8919-534a990ed4e4
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: test-monthly
            product: Test
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: test-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@c8e43ac8
            eventId: 309cc4d6-c21e-4e01-8289-a5767e8272e8
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: test-monthly
            product: Test
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: test-monthly-evergreen
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@c00d61ad
            eventId: b724dc1a-e6bc-4a09-8790-f1d1d81bb8b5
            billingPeriod: MONTHLY
            effectiveDate: 2021-11-29
            plan: testao-monthly
            product: TestAO
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: testao-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

no content

no content

Request Body

One or more subscription resource object corresponding to the base subscriptions need to be specified. Additional, each base subscription resource object can include zero or more subscription resource objects corresponding to add-on subscriptions. Alternatively, only a list of add-on subscription resource objects may be specified along with the base subscription bundle id. Each subscription resource object needs to include accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

In addition, each subscription resource can also include the following optional fields:

• phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
• externalKey - External key corresponding to the subscription.
• billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
• bundleId - Id of the bundle in which to create this subscription. Can be specified only with an add-on subscription resource.

Query Parameters

Name	Type	Required	Default	Description
entitlementDate	string	no	immediately	Date at which the entitlement (sevice) starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
billingDate	string	no	immediately	Date at which the billing starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
renameKeyIfExistsAndUnused	boolean	no	true	If true, rename external key if it exists and is unused
migrated	boolean	no	false	If true, subscription is migrated
callCompletion	boolean	no	false	see below
callTimeoutSec	long	no	unlimited?	Timeout in seconds (see below)

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location parameter is returned in the header which contains the new subscription id.

Retrieve a subscription by id

This API retrieves a subscription resource object based on its subscription id

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

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/subscriptions/d4a919f4-7459-494f-85e5-af8880f63e90' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("905a0636-ab63-40c0-acd4-b461b6808b5d");

Subscription objFromJson = subscriptionApi.getSubscription(subscriptionId, 
                                                           AuditLevel.NONE, 
                                                           requestOptions);

subscription_id = "161692a4-c293-410c-a92f-939c5e3dcba7"

KillBillClient::Model::Subscription.find_by_id(subscription_id, options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '4aab9b96-c2e7-4641-a6d9-db984969201e'

subscriptionApi.get_subscription(subscription_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json
<
{
    "accountId":"581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
    "bundleId":"3b7a754c-4fe3-49a4-a56c-c8f56fc4116c",
    "subscriptionId":"d4a919f4-7459-494f-85e5-af8880f63e90",
    "externalKey":"somethingSpecial",
    "bundleExternalKey":"somethingAlsoSpecial",
    "startDate":"2018-07-19",
    "productName":"Super",
    "productCategory":"BASE",
    "billingPeriod":"MONTHLY",
    "phaseType":"TRIAL",
    "priceList":"DEFAULT",
    "planName":"super-monthly",
    "state":"ACTIVE",
    "sourceType":"NATIVE",
    "cancelledDate":null,
    "chargedThroughDate":"2018-07-19",
    "billingStartDate":"2018-07-19",
    "billingEndDate":null,
    "billCycleDayLocal":18,
    "events":
    [
        {"
            eventId":"d1fc7c9a-bdcd-447c-90f4-72c8de37d457",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-07-19",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"START_ENTITLEMENT",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement-service",
            "serviceStateName":"ENT_STARTED",
            "phase":"super-monthly-trial",
            "auditLogs":[]
        },
        {
            "eventId":"e1cea834-9c21-450a-8ff5-8e1ebef705d1",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-07-19",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"START_BILLING",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"billing-service",
            "serviceStateName":"START_BILLING",
            "phase":"super-monthly-trial",
            "auditLogs":[]
        },
        {
            "eventId":"c9045227-4638-46ca-9a4a-2d3086168505",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-08-18",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"PHASE",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement+billing-service",
            "serviceStateName":"PHASE",
            "phase":"super-monthly-evergreen",
            "auditLogs":[]
        }
    ],
    "priceOverrides":null,
    "prices":
    [
        {
            "planName":"super-monthly",
            "phaseName":"super-monthly-trial",
            "phaseType":"TRIAL",
            "fixedPrice":0,
            "recurringPrice":null,
            "usagePrices":[]
        },
        {
            "planName":"super-monthly",
            "phaseName":"super-monthly-evergreen",
            "phaseType":"EVERGREEN",
            "fixedPrice":null,
            "recurringPrice":1000.00,
            "usagePrices":[]
        }
    ],
    "auditLogs":[]}

class Subscription {
    org.killbill.billing.client.model.gen.Subscription@c620bf78
    accountId: e903d1d6-7423-40fe-8ab7-d9d449484cda
    bundleId: 603db1e6-299e-4b8b-9dfc-beecccca39b2
    subscriptionId: b0f8f527-78c6-4fef-8fb2-53c9ed60a714
    externalKey: 99999
    bundleExternalKey: 88888
    startDate: 2012-04-25
    productName: Shotgun
    productCategory: BASE
    billingPeriod: ANNUAL
    phaseType: TRIAL
    priceList: DEFAULT
    planName: shotgun-annual
    state: ACTIVE
    sourceType: NATIVE
    cancelledDate: null
    chargedThroughDate: 2012-04-25
    billingStartDate: 2012-04-25
    billingEndDate: null
    billCycleDayLocal: 25
    events: [class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@c8078c46
        eventId: 7227bab2-b394-42de-b40c-97cecfd1d9ae
        billingPeriod: ANNUAL
        effectiveDate: 2012-04-25
        plan: shotgun-annual
        product: Shotgun
        priceList: DEFAULT
        eventType: START_ENTITLEMENT
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: entitlement-service
        serviceStateName: ENT_STARTED
        phase: shotgun-annual-trial
        auditLogs: []
    }, class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@1be0ca21
        eventId: ce8578e7-553f-45d7-a4d1-2abb7e625f64
        billingPeriod: ANNUAL
        effectiveDate: 2012-04-25
        plan: shotgun-annual
        product: Shotgun
        priceList: DEFAULT
        eventType: START_BILLING
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: billing-service
        serviceStateName: START_BILLING
        phase: shotgun-annual-trial
        auditLogs: []
    }, class EventSubscription {
        org.killbill.billing.client.model.gen.EventSubscription@f0472744
        eventId: 26d5ea05-b91d-43e6-8aa2-ac0ac82f6a95
        billingPeriod: ANNUAL
        effectiveDate: 2012-05-25
        plan: shotgun-annual
        product: Shotgun
        priceList: DEFAULT
        eventType: PHASE
        isBlockedBilling: false
        isBlockedEntitlement: false
        serviceName: entitlement+billing-service
        serviceStateName: PHASE
        phase: shotgun-annual-evergreen
        auditLogs: []
    }]
    priceOverrides: null
    prices: [class PhasePrice {
        planName: shotgun-annual
        phaseName: shotgun-annual-trial
        phaseType: TRIAL
        fixedPrice: 0
        recurringPrice: null
        usagePrices: []
    }, class PhasePrice {
        planName: shotgun-annual
        phaseName: shotgun-annual-evergreen
        phaseType: EVERGREEN
        fixedPrice: null
        recurringPrice: 249.95
        usagePrices: []
    }]
    auditLogs: []
}

{
   "accountId":"0cdaeca7-4984-47dc-b245-7c32627f26cd",
   "bundleId":"d1f4ca8d-be47-4e64-84ce-f697b42d4182",
   "subscriptionId":"161692a4-c293-410c-a92f-939c5e3dcba7",
   "externalKey":"d1f4ca8d-be47-4e64-84ce-f697b42d4182",
   "bundleExternalKey":"a4f4ca8d-3447-4e64-84ce-6697b42d419c",
   "startDate":"2013-08-01",
   "productName":"Basic",
   "productCategory":"BASE",
   "billingPeriod":"MONTHLY",
   "phaseType":"EVERGREEN",
   "priceList":"DEFAULT",
   "planName":"basic-monthly-in-advance",
   "state":"ACTIVE",
   "sourceType":"NATIVE",
   "chargedThroughDate":"2013-09-01",
   "billingStartDate":"2013-08-01",
   "billCycleDayLocal":1,
   "events":[
      {
         "eventId":"dda11bf3-f74a-4c42-83e1-0f43a41389af",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_ENTITLEMENT",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement-service",
         "serviceStateName":"ENT_STARTED",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      },
      {
         "eventId":"6901117c-4ce0-4eb6-8642-380823490fae",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_BILLING",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"billing-service",
         "serviceStateName":"START_BILLING",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      }
   ],
   "prices":[
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"asic-monthly-in-advance-trial",
         "phaseType":"TRIAL",
         "fixedPrice":0,
         "recurringPrice":null,
         "usagePrices":[]
      },
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"basic-monthly-in-advance-evergreen",
         "phaseType":"EVERGREEN",
         "fixedPrice":null,
         "recurringPrice":500.0,
         "usagePrices":[]
      }
   ],
   "auditLogs":[]
}

{'account_id': '3b1a5a67-f0ac-475c-9aad-735d309f0c1f',
 'audit_logs': [],
 'bill_cycle_day_local': 13,
 'billing_end_date': None,
 'billing_period': 'MONTHLY',
 'billing_start_date': datetime.date(2018, 5, 14),
 'bundle_id': 'e5590623-ccd4-4a8a-be26-008ce7c02b3b',
 'cancelled_date': None,
 'charged_through_date': None,
 'events': [{'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 5, 14),
             'event_id': '46335d3d-8234-49c3-af1a-dcf8cd354ef3',
             'event_type': 'START_ENTITLEMENT',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-trial',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'entitlement-service',
             'service_state_name': 'ENT_STARTED'},
            {'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 5, 14),
             'event_id': 'a14d6512-7479-46e0-b72b-81dff575d1d4',
             'event_type': 'START_BILLING',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-trial',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'billing-service',
             'service_state_name': 'START_BILLING'},
            {'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 6, 13),
             'event_id': '27408c65-46b8-4bc9-a7ee-c80d6e5fb9b5',
             'event_type': 'PHASE',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-evergreen',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'entitlement+billing-service',
             'service_state_name': 'PHASE'}],
 'external_key': 'e5590623-ccd4-4a8a-be26-008ce7c02b3b',
 'phase_type': 'TRIAL',
 'plan_name': 'standard-monthly',
 'price_list': 'DEFAULT',
 'prices': [{'fixed_price': 0.0,
              'phase_name': 'standard-monthly-trial',
              'phase_type': 'TRIAL',
              'plan_name': 'standard-monthly',
              'recurring_price': None,
              'usage_prices': []},
             {'fixed_price': None,
              'phase_name': 'standard-monthly-evergreen',
              'phase_type': 'EVERGREEN',
              'plan_name': 'standard-monthly',
              'recurring_price': 100.0,
              'usage_prices': []}],  
 'product_category': 'BASE',
 'product_name': 'Standard',
 'source_type': 'NATIVE',
 'start_date': datetime.date(2018, 5, 14),
 'state': 'ACTIVE',
 'subscription_id': '4aab9b96-c2e7-4641-a6d9-db984969201e'}

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a subscription resource object.

Retrieve a subscription by key

This API retrieves a subscription resource object based on its external key

HTTP Request

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

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/subscriptions?externalKey=somethingSpecial'

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

String externalKey = "somethingSpecial";
Subscription objFromJson = subscriptionApi.getSubscriptionByKey(externalKey, requestOptions);

external_key = "somethingSpecial"
KillBillClient::Model::Subscription.find_by_external_key(external_key, options)

subscriptionApi = killbill.api.SubscriptionApi()
external_key = 'somethingSpecial'
subscriptionApi.get_subscription_by_key(external_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json
<
{
  "accountId": "1f979085-1765-471b-878a-5f640db4d831",
  "bundleId": "8815e8c0-afab-41b9-b793-cb8fef2382e4",
  "bundleExternalKey": "8815e8c0-afab-41b9-b793-cb8fef2382e4",
  "subscriptionId": "8e5c5339-1cad-46c6-ab18-3d5ddc1b2414",
  "externalKey": "somethingSpecial",
  "startDate": "2020-01-08",
  "productName": "Pistol",
  "productCategory": "BASE",
  "billingPeriod": "MONTHLY",
  "phaseType": "EVERGREEN",
  "priceList": "notrial",
  "planName": "pistol-monthly-notrial",
  "state": "ACTIVE",
  "sourceType": "NATIVE",
  "cancelledDate": null,
  "chargedThroughDate": "2020-05-08",
  "billingStartDate": "2020-01-08",
  "billingEndDate": null,
  "billCycleDayLocal": 8,
  "events": [
    {
      "eventId": "1d24928e-790d-4dc9-8a88-c4eaa56de392",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2020-01-08",
      "plan": "pistol-monthly-notrial",
      "product": "Pistol",
      "priceList": "notrial",
      "eventType": "START_ENTITLEMENT",
      "isBlockedBilling": false,
      "isBlockedEntitlement": false,
      "serviceName": "entitlement-service",
      "serviceStateName": "ENT_STARTED",
      "phase": "pistol-monthly-notrial-evergreen",
      "auditLogs": []
    },
    {
      "eventId": "3aaa3239-2bc6-4f04-977b-fce5de098af8",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2020-01-08",
      "plan": "pistol-monthly-notrial",
      "product": "Pistol",
      "priceList": "notrial",
      "eventType": "START_BILLING",
      "isBlockedBilling": false,
      "isBlockedEntitlement": false,
      "serviceName": "billing-service",
      "serviceStateName": "START_BILLING",
      "phase": "pistol-monthly-notrial-evergreen",
      "auditLogs": []
    }
  ],
  "priceOverrides": null,
  "prices": [
    {
      "planName": "pistol-monthly-notrial",
      "phaseName": "pistol-monthly-notrial-evergreen",
      "phaseType": "EVERGREEN",
      "fixedPrice": null,
      "recurringPrice": 19.95,
      "usagePrices": []
    }
  ],
  "auditLogs": []
}

{
   "accountId":"0cdaeca7-4984-47dc-b245-7c32627f26cd",
   "bundleId":"d1f4ca8d-be47-4e64-84ce-f697b42d4182",
   "subscriptionId":"161692a4-c293-410c-a92f-939c5e3dcba7",
   "externalKey":"somethingSpecial",
   "bundleExternalKey":"a4f4ca8d-3447-4e64-84ce-6697b42d419c",
   "startDate":"2013-08-01",
   "productName":"Basic",
   "productCategory":"BASE",
   "billingPeriod":"MONTHLY",
   "phaseType":"EVERGREEN",
   "priceList":"DEFAULT",
   "planName":"basic-monthly-in-advance",
   "state":"ACTIVE",
   "sourceType":"NATIVE",
   "chargedThroughDate":"2013-09-01",
   "billingStartDate":"2013-08-01",
   "billCycleDayLocal":1,
   "events":[
      {
         "eventId":"dda11bf3-f74a-4c42-83e1-0f43a41389af",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_ENTITLEMENT",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement-service",
         "serviceStateName":"ENT_STARTED",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      },
      {
         "eventId":"6901117c-4ce0-4eb6-8642-380823490fae",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"basic-monthly-in-advance",
         "product":"Basic",
         "priceList":"DEFAULT",
         "eventType":"START_BILLING",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"billing-service",
         "serviceStateName":"START_BILLING",
         "phase":"basic-monthly-in-advance-evergreen",
         "auditLogs":[]
      }
   ],
   "prices":[
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"asic-monthly-in-advance-trial",
         "phaseType":"TRIAL",
         "fixedPrice":0,
         "recurringPrice":null,
         "usagePrices":[]
      },
      {
         "planName":"basic-monthly-in-advance",
         "phaseName":"basic-monthly-in-advance-evergreen",
         "phaseType":"EVERGREEN",
         "fixedPrice":null,
         "recurringPrice":500.0,
         "usagePrices":[]
      }
   ],
   "auditLogs":[]
}

{'account_id': '3b1a5a67-f0ac-475c-9aad-735d309f0c1f',
 'audit_logs': [],
 'bill_cycle_day_local': 13,
 'billing_end_date': None,
 'billing_period': 'MONTHLY',
 'billing_start_date': datetime.date(2018, 5, 14),
 'bundle_id': 'e5590623-ccd4-4a8a-be26-008ce7c02b3b',
 'cancelled_date': None,
 'charged_through_date': None,
 'events': [{'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 5, 14),
             'event_id': '46335d3d-8234-49c3-af1a-dcf8cd354ef3',
             'event_type': 'START_ENTITLEMENT',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-trial',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'entitlement-service',
             'service_state_name': 'ENT_STARTED'},
            {'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 5, 14),
             'event_id': 'a14d6512-7479-46e0-b72b-81dff575d1d4',
             'event_type': 'START_BILLING',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-trial',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'billing-service',
             'service_state_name': 'START_BILLING'},
            {'audit_logs': [],
             'billing_period': 'MONTHLY',
             'effective_date': datetime.date(2018, 6, 13),
             'event_id': '27408c65-46b8-4bc9-a7ee-c80d6e5fb9b5',
             'event_type': 'PHASE',
             'is_blocked_billing': False,
             'is_blocked_entitlement': False,
             'phase': 'standard-monthly-evergreen',
             'plan': 'standard-monthly',
             'price_list': 'DEFAULT',
             'product': 'Standard',
             'service_name': 'entitlement+billing-service',
             'service_state_name': 'PHASE'}],
 'external_key': 'somethingSpecial',
 'phase_type': 'TRIAL',
 'plan_name': 'standard-monthly',
 'price_list': 'DEFAULT',
 'prices': [{'fixed_price': 0.0,
              'phase_name': 'standard-monthly-trial',
              'phase_type': 'TRIAL',
              'plan_name': 'standard-monthly',
              'recurring_price': None,
              'usage_prices': []},
             {'fixed_price': None,
              'phase_name': 'standard-monthly-evergreen',
              'phase_type': 'EVERGREEN',
              'plan_name': 'standard-monthly',
              'recurring_price': 100.0,
              'usage_prices': []}],
 'product_category': 'BASE',
 'product_name': 'Standard',
 'source_type': 'NATIVE',
 'start_date': datetime.date(2018, 5, 14),
 'state': 'ACTIVE',
 'subscription_id': '4aab9b96-c2e7-4641-a6d9-db984969201e'}

Query Parameters

Name	Type	Required	Default	Description
externalKey	String	yes	none	The subscription external key
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a subscription resource object.

Update the BCD associated with a subscription

This API allows you to change the Bill Cycle Date, BCD, for a given subscription. This only applies to subscriptions whose recurring term is month based -- e.g MONTHLY, ANNUAL, ...

For example if a given subscription was invoiced on the 1st, then one could use this API to realign invoicing, let's say on the 16th.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/bcd

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ "billCycleDayLocal": 16 }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/bcd' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("905a0636-ab63-40c0-acd4-b461b6808b5d");

Subscription updatedSubscription = new Subscription();
updatedSubscription.setSubscriptionId(subscriptionId);
updatedSubscription.setBillCycleDayLocal(9);

LocalDate effectiveFromDate = null;

subscriptionApi.updateSubscriptionBCD(subscriptionId, 
                                      updatedSubscription, 
                                      effectiveFromDate, 
                                      requestOptions);

subscription                      = KillBillClient::Model::Subscription.new
subscription.subscription_id      = "161692a4-c293-410c-a92f-939c5e3dcba7"
subscription.bill_cycle_day_local = 16

effective_from_date  = '2018-08-16'
force_past_effective_date = nil

subscription.update_bcd(user, 
                        reason, 
                        comment, 
                        effective_from_date, 
                        force_past_effective_date, 
                        options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '161692a4-c293-410c-a92f-939c5e3dcba7'
body = Subscription(subscription_id=subscription_id,
                    bill_cycle_day_local=26)

subscriptionApi.update_subscription_bcd(subscription_id,
                                        body,
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Request Body

The new BCD needs to be specified in the request body via the billCycleDayLocal field.

Query Parameters

Name	Type	Required	Default	Description
effectiveFromDate	string	no	immediate	Date on which this change becomes effective in yyyy-mm-dd format.
forceNewBcdWithPastEffectiveDate	boolean	no	false	See below

By default the effective date must be in the future so as to not modify existing invoices. Setting forceNewBcdWithPastEffectiveDate to true allows the date to be set in the past.

Secondly, even after this endpoint is executed, the Retrieve a Subscription endpoint will still return the old BCD until an invoice is generated on the new BCD.

Response

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

Change subscription plan

This API allows you to upgrade or downgrade a given subscription to a new Plan.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "productName": "Sports", 
            "billingPeriod": "MONTHLY", 
            "priceList": "DEFAULT"
        }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712'

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("905a0636-ab63-40c0-acd4-b461b6808b5d");

Subscription newInput = new Subscription();
newInput.setSubscriptionId(subscriptionId);

// Specify the product, billing period and price list
newInput.setProductName("Shotgun");
newInput.setBillingPeriod(BillingPeriod.MONTHLY);
newInput.setPriceList("DEFAULT");

// Alternatively, you can specify the plan name
newInput.setPlanName("shotgun-monthly");

LocalDate requestedDate = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

//specify either requestedDate or BillingActionPolicy
subscriptionApi.changeSubscriptionPlan(subscriptionId, 
                                       newInput, 
                                       requestedDate, 
                                       BillingActionPolicy.IMMEDIATE, 
                                       NULL_PLUGIN_PROPERTIES, 
                                       requestOptions);

input = {
           :productName => 'Super', 
           :billingPeriod => 'MONTHLY', 
           :priceList => 'DEFAULT'
         }

requested_date = nil
billing_policy = nil
call_completion = false
target_phase_type = nil

subscription.change_plan(input, 
                         user, 
                         reason, 
                         comment, 
                         requested_date, 
                         billing_policy,
                         target_phase_type, 
                         call_completion, 
                         options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '97278000-72fd-45d7-9b67-e44690bdb074'
body = Subscription(product_name='Super',
                    billing_period='MONTHLY',
                    price_list='DEFAULT')

subscriptionApi.change_subscription_plan(subscription_id,
                                         body,
                                         created_by,
                                         api_key,
                                         api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

{
   "accountId":"986c5d4e-b322-4d71-ad24-e3bf6e38734a",
   "bundleId":"b0b9da5f-6844-417b-ac97-d7e8df07c26a",
   "subscriptionId":"97278000-72fd-45d7-9b67-e44690bdb074",
   "externalKey":"986c5d4e-b322-4d71-ad24-e3bf6e38734a-452347",
   "bundleExternalKey":"765c5d4e-b322-4d71-6544-e3bf6e38734a-cd2347",
   "startDate":"2013-08-01",
   "productName":"Super",
   "productCategory":"BASE",
   "billingPeriod":"MONTHLY",
   "phaseType":"TRIAL",
   "priceList":"DEFAULT",
   "planName":"super-monthly",
   "state":"ACTIVE",
   "sourceType":"NATIVE",
   "chargedThroughDate":"2013-08-01",
   "billingStartDate":"2013-08-01",
   "billCycleDayLocal":31,
   "events":[
      {
         "eventId":"b2c4195a-0888-44e4-91a7-537b20b08bd8",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"sports-monthly",
         "product":"Sports",
         "priceList":"DEFAULT",
         "eventType":"START_ENTITLEMENT",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement-service",
         "serviceStateName":"ENT_STARTED",
         "phase":"sports-monthly-trial",
         "auditLogs":[]
      },
      {
         "eventId":"0c15d9ba-f0f3-40e6-83d7-2d84af703d06",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-01",
         "plan":"sports-monthly",
         "product":"Sports",
         "priceList":"DEFAULT",
         "eventType":"START_BILLING",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"billing-service",
         "serviceStateName":"START_BILLING",
         "phase":"sports-monthly-trial",
         "auditLogs":[]
      },
      {
         "eventId":"b675c39f-eeef-4cc1-8ffc-e50f51e8a84a",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-02",
         "plan":"super-monthly",
         "product":"Super",
         "priceList":"DEFAULT",
         "eventType":"CHANGE",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement+billing-service",
         "serviceStateName":"CHANGE",
         "phase":"super-monthly-trial",
         "auditLogs":[]
      },
      {
         "eventId":"e411fe3e-6d38-4256-bd96-867f3a50c634",
         "billingPeriod":"MONTHLY",
         "effectiveDate":"2013-08-31",
         "plan":"super-monthly",
         "product":"Super",
         "priceList":"DEFAULT",
         "eventType":"PHASE",
         "isBlockedBilling":false,
         "isBlockedEntitlement":false,
         "serviceName":"entitlement+billing-service",
         "serviceStateName":"PHASE",
         "phase":"super-monthly-evergreen",
         "auditLogs":[]
      }
   ],
   "prices":[
      {
         "planName":"sports-monthly",
         "phaseName":"sports-monthly-trial",
         "phaseType":"TRIAL",
         "fixedPrice":0,
         "recurringPrice":null,
         "usagePrices":[]
      },
      {
         "planName":"sports-monthly",
         "phaseName":"sports-monthly-evergreen",
         "phaseType":"EVERGREEN",
         "fixedPrice":null,
         "recurringPrice":500.0,
         "usagePrices":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A subscription resource object specifying either the planName or a combination of productName, billingPeriod and priceList.

Query Parameters

Name	Type	Required	Default	Description
billingPolicy	string	no	default	Billing policy that will be used to make this change effective (see below)
requestedDate	string	no	immediate	Date at which this change should become effective in yyyy-mm-dd format.
callCompletion	boolean	no	false	see below
callTimeoutSec	long	no	unlimited?	Timeout in seconds (see below)

billingPolicy: Possible values are START_OF_TERM, END_OF_TERM, IMMEDIATE, or ILLEGAL

requestedDate: This date is only used if no billingPolicy was specified.

Changing the plan associated to a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Response

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

Undo a pending change plan on a subscription

This endpoint allows a pending Plan change (plan change request with a future effective date) for a given subscription to be canceled. Note that if the plan change is already effective, then it cannot be undone.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/undoChangePlan

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/undoChangePlan' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("1bb4b638-3886-4f73-90a5-89eb6d1bcf7f");
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

subscriptionApi.undoChangeSubscriptionPlan(subscriptionId, 
                                           NULL_PLUGIN_PROPERTIES, 
                                           requestOptions);

subscription.undo_change_plan(user, 
                              reason, 
                              comment, 
                              options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = 'f5bb14ed-c6e8-4895-8d4e-34422e12cdfa'

subscriptionApi.undo_change_subscription_plan(subscription_id,
                                              created_by,
                                              api_key,
                                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

None.

Response

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

Cancel a subscription

This API cancels an existing subscription.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

Example Request:

curl  -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712'

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("905a0636-ab63-40c0-acd4-b461b6808b5d");
LocalDate requestedDate = null;
EntitlementActionPolicy entitlementPolicy = null;
BillingActionPolicy billingPolicy = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

subscriptionApi.cancelSubscriptionPlan(subscriptionId,
                                       requestedDate, 
                                       entitlementPolicy, 
                                       billingPolicy, 
                                       NULL_PLUGIN_PROPERTIES, 
                                       requestOptions);

requested_date = nil
entitlement_policy = nil
billing_policy = nil
use_requested_date_for_billing = nil

subscription.cancel(user, 
                    reason, 
                    comment, 
                    requested_date, 
                    entitlement_policy, 
                    billing_policy, 
                    use_requested_date_for_billing, 
                    options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = 'ee508b5b-46b8-42a7-8988-16c0470de4ae'

subscriptionApi.cancel_subscription_plan(subscription_id, 
                                         created_by,
                                         api_key,
                                         api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	immediate	Date at which this change should become effective in yyyy-mm-dd format.
entitlementPolicy	string	no	IMMEDIATE	entitlement policy (see below)
billingPolicy	string	no	default policy from catalog if present, otherwise END_OF_TERM	billing policy (see below)
useRequestedDateForBilling	boolean	no	false	use requestedDate for billing
callCompletion	boolean	no	false	see below
callTimeoutSec	long	no	unlimited?	Timeout in seconds (see below)

entitlementPolicy: Possible values are IMMEDIATE, END_OF_TERM

billingPolicy: Possible values are START_OF_TERM, END_OF_TERM, or IMMEDIATE

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Since we offer the ability to control the cancelation date for both entitlement (service) and billing either through policies, dates or null values (now), it is important to understand how those parameters work:

• If entitlementPolicy has been defined, the requestedDate is ignored, and we either default to the catalog defined billingPolicy for this Plan, or use the one provided in this API.
• If not, the requestedDate is used to compute the entitlement cancelation date, and the null value means change should be immediate. The billing date will then be computed the following way:
  • If billingPolicy has been specified, it is used to compute the billing cancelation date
  • If billingPolicy has not been specified, we either use the requestedDate when useRequestedDateForBilling is true or default to the catalog defined billingPolicy for this Plan

So, the common use case would require the following:

• Immediate cancelation: This will create a prorated credit unless this aligns with the subscription charged through date (CTD), that is, the date up to which it was invoiced, and then from an entitlement point of view it will deactivate service immediately. In order to achieve this result, one can pass the following parameters: entitlementPolicy=IMMEDIATE and billingPolicy=IMMEDIATE; alternatively passing no parameters and therefore a null requestedDate would produce the same result.
• EOT cancelation: This will not create any proration and will keep the service active until the end of the period (CTD). In order to achieve this result, one can pass the following parameters: entitlementPolicy=END_OF_TERM and billingPolicy=END_OF_TERM.

The reason for all this complexity is to allow to control entitlement and billing date separately, and also avoid users to have to compute dates to achieve certain behavior by relying on well defined policies.

Other Notes If a subscription is created with a future date and if the cancel method is invoked for immediate cancellation, the cancellation takes effect only after the subscription creation date is reached. Thus, the subscription remains in PENDING state until the subscription creation date is reached after which it is moved to the CANCELLED state.

Returns

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

Un-cancel a subscription

This endpoint allows you to undo a pending cancellation (cancellation request with a future effective date) for a given subscription.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/uncancel

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/uncancel' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("1bb4b638-3886-4f73-90a5-89eb6d1bcf7f");
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

subscriptionApi.uncancelSubscriptionPlan(subscriptionId, 
                                         NULL_PLUGIN_PROPERTIES, 
                                         requestOptions);

subscription.uncancel(user, 
                      reason, 
                      comment, 
                      options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = 'f5bb14ed-c6e8-4895-8d4e-34422e12cdfa'

subscriptionApi.uncancel_subscription_plan(subscription_id,
                                           created_by,
                                           api_key,
                                           api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

None.

Returns

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

Blocking State

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

Block a subscription

Provides a low level interface to add a BlockingState event for this subscription.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/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 "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "stateName": "STATE",
            "service": "ServiceStateService",
            "isBlockChange": false,
            "isBlockEntitlement": false,
            "isBlockBilling": false
    }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/block' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("161692a4-c293-410c-a92f-939c5e3dcba7");

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 = ImmutableMap.<String, String>of();

BlockingStates result = subscriptionApi.addSubscriptionBlockingState(subscriptionId,
                                                                     blockingState,
                                                                     requestedDate,
                                                                     pluginProperty,
                                                                     requestOptions);

subscription = KillBillClient::Model::Subscription.new
subscription.subscription_id = "161692a4-c293-410c-a92f-939c5e3dcba7"

state_name = 'STATE1'
service = 'ServiceStateService'
block_change = false
block_entitlement = false
block_billing = false
requested_date = nil

subscription.set_blocking_state(state_name, 
                                service, 
                                block_change, 
                                block_entitlement, 
                                block_billing, 
                                requested_date, 
                                user, 
                                reason,
                                comment, 
                                options)

subscriptionApi = killbill.api.SubscriptionApi()
body = BlockingState(state_name='STATE1',
                     service='ServiceStateService',
                     is_block_change=False,
                     is_block_entitlement=False,
                     is_block_billing=False)

subscriptionApi.add_subscription_blocking_state(subscription_id,
                                                body,
                                                created_by,
                                                api_key,
                                                api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Location: http://127.0.0.1:8080/1.0/kb/accounts/581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3/block?blockingStateTypes=SUBSCRIPTION
< Content-Length: 0

[class BlockingState {
    org.killbill.billing.client.model.gen.BlockingState@bf898dea
    blockedId: 161692a4-c293-410c-a92f-939c5e3dcba7
    stateName: ENT_STARTED
    service: entitlement-service
    isBlockChange: false
    isBlockEntitlement: false
    isBlockBilling: false
    effectiveDate: 2012-04-25T00:03:42.000Z
    type: SUBSCRIPTION
    auditLogs: []
}, class BlockingState {
    org.killbill.billing.client.model.gen.BlockingState@fd3732d8
    blockedId: 161692a4-c293-410c-a92f-939c5e3dcba7
    stateName: STATE1
    service: ServiceStateService
    isBlockChange: false
    isBlockEntitlement: false
    isBlockBilling: false
    effectiveDate: 2013-08-01T00:03:42.000Z
    type: SUBSCRIPTION
    auditLogs: []
}]

no content

no content

Request Body

A blocking state resource representing the intended new blocking state. For example,

{
  "blockedId": "943c4fd0-9000-4975-a3a8-09712223e1f8",
  "stateName": "STATE1",
  "service": "ServiceStateService",
  "isBlockChange": false,
  "isBlockEntitlement": false,
  "isBlockBilling": true,
  "effectiveDate": "2020-07-18T18:22:30.376Z",
  "type": "SUBSCRIPTION"
}

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	immediate	Date to begin blocking

Response

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

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resources. For more on custom fields see Custom Fields. These endpoints manage custom fields associated with Subscription objects.

Add custom fields to subscription

Adds one or more custom fields to a subscription object. Existing custom fields are not disturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/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 "X-Killbill-CreatedBy: demo" \
    -d '[{ 
            "objectId": "77e23878-8b9d-403b-bf31-93003e125712",
            "objectType": "SUBSCRIPTION",
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

subscriptionApi.createSubscriptionCustomFields(subscriptionId, 
                                               customFields, 
                                               requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'SUBSCRIPTION'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

subscription.add_custom_field(custom_field, 
                              user,
                              reason,
                              comment,
                              options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
body = CustomField(name='Test Custom Field', value='test_value')

subscriptionApi.create_subscription_custom_fields(subscription_id,
                                                  [body],
                                                  created_by,
                                                  api_key,
                                                  api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: SUBSCRIPTION
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"SUBSCRIPTION",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

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 subscription.

Retrieve subscription custom fields

Returns any custom field objects associated with the specified subscription

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

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/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

List<CustomField> customFields = subscriptionApi.getSubscriptionCustomFields(subscriptionId,
                                                                             AuditLevel.NONE,
                                                                             requestOptions);

audit = 'NONE'

subscription.custom_fields(audit, options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '642ee0ac-972b-4cdf-b9ae-ab8f9bb9bc05'

subscriptionApi.get_subscription_custom_fields(subscription_id,
                                               api_key,
                                               api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 Ok
< Content-Type: application/json
<
[
    {
        "customFieldId":"439ed0f8-9b37-4688-bace-e2595b1d3801",
        "objectId":"77e23878-8b9d-403b-bf31-93003e125712",
        "objectType":"SUBSCRIPTION",
        "name":"Test Custom Field",
        "value":"test_value",
        "auditLogs":[]
    }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: SUBSCRIPTION
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"SUBSCRIPTION",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '31a21da4-1eae-4f83-b9e4-49c53217d33e',
 'name': 'Test Custom Field',
 'object_id': '642ee0ac-972b-4cdf-b9ae-ab8f9bb9bc05',
 'object_type': 'SUBSCRIPTION',
 'value': 'test_value'}]

Query Parameters

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

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for a subscription

Modifies the value of one or more existing custom fields associated with a subscription. 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/subscriptions/{subscriptionId}/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 "X-Killbill-CreatedBy: demo" \
    -d '[{ 
            "customFieldId": "439ed0f8-9b37-4688-bace-e2595b1d3801",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
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);

subscriptionApi.modifySubscriptionCustomFields(subscriptionId, 
                                               customFields, 
                                               requestOptions);

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

subscription.modify_custom_field(custom_field,                                                                                            
                                 user, 
                                 reason,
                                 comment, 
                                 options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
body = CustomField(custom_field_id=custom_field_id, 
                   name='Test Custom Field', 
                   value='test_value')

subscriptionApi.modify_subscription_custom_fields(subscription_id,
                                                  [body],
                                                  created_by,
                                                  api_key,
                                                  api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

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.

Response

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

Remove custom fields from subscription

Delete one or more custom fields from a subscription

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=439ed0f8-9b37-4688-bace-e2595b1d3801' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = ImmutableList.<UUID>of(customFieldsId);

subscriptionApi.deleteSubscriptionCustomFields(subscriptionId, 
                                               customFieldsList, 
                                               requestOptions);

custom_field_id = custom_field.id

subscription.remove_custom_field(custom_field_id,                                                                                            
                                 user, 
                                 reason,
                                 comment, 
                                 options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'

subscriptionApi.delete_subscription_custom_fields(subscription_id,
                                                  created_by,
                                                  api_key,
                                                  api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	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

See section Account Tags for an introduction.

The are no system tags applicable for a Subscription.

Add tags to subscription

This API adds one or more tags to a subscription. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/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 "X-Killbill-CreatedBy: demo" \
    -d '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
  'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("1bb4b638-3886-4f73-90a5-89eb6d1bcf7f");
UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

subscriptionApi.createSubscriptionTags(subscriptionId, 
                                                     ImmutableList.<UUID>of(tagDefinitionId), 
                                                     requestOptions);

tag_name = 'foo'

subscription.add_tag(tag_name,
                     user,
                     reason,
                     comment,
                     options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

subscriptionApi.create_subscription_tags(subscription_id,
                                         tag,
                                         created_by,
                                         api_key,
                                         api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: SUBSCRIPTION
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"SUBSCRIPTION",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

no content

Request Body

A JSON array containing one or more strings giving the UUID of tag definitions for the user tags to be added.

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 subscription.

Retrieve all tags

Retrieve subscription tags

Retrieve all tags attached to this subscription.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/tags

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/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags' 

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("1bb4b638-3886-4f73-90a5-89eb6d1bcf7f");

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = subscriptionApi.getSubscriptionTags(subscriptionId, 
                                                     includedDeleted, 
                                                     AuditLevel.FULL, 
                                                     requestOptions);

included_deleted = false
audit = 'NONE'

subscription.tags(included_deleted,
                  audit,
                  options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = 'f5bb14ed-c6e8-4895-8d4e-34422e12cdfa'

subscriptionApi.get_subscription_tags(subscription_id,
                                      api_key,
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
    {
        "tagId":"d0513754-56a9-4694-abb1-3ac46c72e861",
        "objectType":"SUBSCRIPTION",
        "objectId":"77e23878-8b9d-403b-bf31-93003e125712",
        "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
        "tagDefinitionName":"foo",
        "auditLogs":[]
    }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: SUBSCRIPTION
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"SUBSCRIPTION",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'object_id': 'f5bb14ed-c6e8-4895-8d4e-34422e12cdfa',
 'object_type': 'SUBSCRIPTION',
 'tag_definition_id': '353752dd-9041-4450-b782-a8bb03a923c8',
 'tag_definition_name': 'foo',
 'tag_id': 'a1fd0122-1ec8-4bc3-b71e-ab2a76ae5957'}]

Query Parameters

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

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from subscription

This API removes a list of tags attached to a subscription.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/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" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'  

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("1bb4b638-3886-4f73-90a5-89eb6d1bcf7f");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

subscriptionApi.deleteSubscriptionTags(subscriptionId, 
                                       ImmutableList.<UUID>of(tagDefinitionId), 
                                       requestOptions);

tag_name = 'foo'

subscription.remove_tag(tag_name,
                        user,
                        reason,
                        comment,
                        options)

subscriptionApi = killbill.api.SubscriptionApi()
subscription_id = 'f5bb14ed-c6e8-4895-8d4e-34422e12cdfa'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

subscriptionApi.delete_subscription_tags(subscription_id,
                                         created_by,
                                         api_key,
                                         api_secret,
                                         tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of strings	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 subscription audit logs with history by subscription id

Retrieve a list of audit log records showing events that occurred involving changes to the subscription. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/auditLogsWithHistory

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/subscriptions/70b6856e-6938-495f-9ae9-0a8ec0571c37/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionId = UUID.fromString("bc9b98e8-7497-4330-aa42-1fbc71a3d19c");

List<AuditLog> auditLog = subscriptionApi.getSubscriptionAuditLogsWithHistory(subscriptionId,                                                                                                                                                                           requestOptions);

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION",
    "objectId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
    "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": 465,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "bundleId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "category": "BASE",
      "startDate": "2019-02-22T22:38:10.000Z",
      "bundleStartDate": "2019-02-22T22:38:10.000Z",
      "chargedThroughDate": null,
      "migrated": false,
      "tableName": "SUBSCRIPTIONS",
      "historyTableName": "SUBSCRIPTION_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION",
    "objectId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
    "changedBy": "SubscriptionBaseTransition",
    "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": 465,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "bundleId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "category": "BASE",
      "startDate": "2019-02-22T22:38:10.000Z",
      "bundleStartDate": "2019-02-22T22:38:10.000Z",
      "chargedThroughDate": "2019-03-22T23:35:14.000Z",
      "migrated": false,
      "tableName": "SUBSCRIPTIONS",
      "historyTableName": "SUBSCRIPTION_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

Retrieve subscription event audit logs with history by subscription event id

Retrieve a list of audit log records showing events that occurred involving changes to the subscription, based on a subscription event id. History information (a copy of the full subscription object) is included with each record. The id of a subscription event comes from the timeline api.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/events/{subscriptionEventId}/auditLogsWithHistory

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/subscriptions/events/9a1c85d5-beba-40c8-9268-f73e09c24007/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.SubscriptionApi;
protected SubscriptionApi subscriptionApi;

UUID subscriptionEventId = UUID.fromString("b4b6f990-4456-4009-9e6c-9825a99a1f25");

List<AuditLog> eventAuditLog = subscriptionApi.getSubscriptionEventAuditLogsWithHistory(subscriptionEventId, requestOptions);

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION_EVENT",
    "objectId": "9a1c85d5-beba-40c8-9268-f73e09c24007",
    "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": 1358,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "totalOrdering": 0,
      "eventType": "API_USER",
      "userType": "CREATE",
      "effectiveDate": "2019-02-22T22:38:10.000Z",
      "subscriptionId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
      "planName": "foo-monthly",
      "phaseName": "foo-monthly-evergreen",
      "priceListName": "DEFAULT",
      "billingCycleDayLocal": 0,
      "isActive": true,
      "tableName": "SUBSCRIPTION_EVENTS",
      "historyTableName": "SUBSCRIPTION_EVENT_HISTORY",
      "active": true
    }
  }
]

Query Parameters

None.

Response

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

Bundle

A Bundle is a collection of subscriptions. Grouping certain subscriptions into a bundle is useful to ensure that certain operations propagate to the group. A common example is cancellation. When cancelling a BASE subscription, which is part of a bundle, any ADD_ON subscriptions in the same bundle are also cancelled automatically.

A Bundle is automatically created by the system when creating the intial (BASE) subscription. To add additional subscriptions in the same bundle, one must specify the bundleId for the bundle previously created.

Bundle Resource

The Bundle resource represents a bundle. The attributes contained in this resource are the following:

Name	Type	Generated by	Description
accountId	string	system	UUID for the account
bundleId	string	system	UUID for the bundle
externalKey	string	user	Optional external key for the bundle
subscriptions	array	system	List of subscriptions in the bundle
timeline	array	system	List of events for the bundle.

subscriptions is a read-only array of subscription resources for the subscriptions in this bundle.

timeline is a read-only array of event resources for the events that have occurred for this bundle.

Bundle

These endpoints support the basic operations on bundles. There is no create operation, because a bundle is automatically created when a BASE subscription is created.

Retrieve a bundle by id

This API retrieves a bundle resource object based on its bundle Id.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}

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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("90ec582a-5da8-49d5-a656-c63cbc9d30fd");

Bundle result = bundleApi.getBundle(bundleId, 
                                    AuditLevel.NONE, 
                                    requestOptions);

bundle_id = "5b7a5f2d-4054-412f-b354-b722c2cff4ec"

bundle = KillBillClient::Model::Bundle.new
bundle.find_by_id(bundle_id, options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'

bundleApi.get_bundle(bundle_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

class Bundle {
    org.killbill.billing.client.model.gen.Bundle@efd93c26
    accountId: 11d96ccc-9bfb-4349-8d75-0ae5a7ed8d14
    bundleId: 90ec582a-5da8-49d5-a656-c63cbc9d30fd
    externalKey: 93199
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@256a98cc
        accountId: 11d96ccc-9bfb-4349-8d75-0ae5a7ed8d14
        bundleId: 90ec582a-5da8-49d5-a656-c63cbc9d30fd
        subscriptionId: 2a95b238-719f-4c2d-a63e-f1f34f11dd53
        externalKey: 93199
        startDate: 2012-04-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: CANCELLED
        sourceType: NATIVE
        cancelledDate: 2012-04-25
        chargedThroughDate: 2012-04-25
        billingStartDate: 2012-04-25
        billingEndDate: 2012-04-25
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a883ef63
            eventId: 18719cae-eab1-4f75-9ea7-f1e3135a3e7c
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@856f5bdf
            eventId: 81518934-4418-491b-819c-72ab7c840bd6
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@3ced19b8
            eventId: c0a8f0ce-db27-4371-81f0-74148e36663f
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: STOP_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: true
            serviceName: entitlement-service
            serviceStateName: ENT_CANCELLED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@401111f4
            eventId: 762e80db-d75e-4b67-9ccc-b816a00181b7
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: STOP_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: STOP_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }]
        priceOverrides: [class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePriceOverrides: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@b8eeb095
        accountId: 11d96ccc-9bfb-4349-8d75-0ae5a7ed8d14
        bundleId: 90ec582a-5da8-49d5-a656-c63cbc9d30fd
        externalKey: 93199
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@d88c1e6d
            eventId: 18719cae-eab1-4f75-9ea7-f1e3135a3e7c
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@92c880de
            eventId: 81518934-4418-491b-819c-72ab7c840bd6
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@4871bbf6
            eventId: c0a8f0ce-db27-4371-81f0-74148e36663f
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: STOP_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: true
            serviceName: entitlement-service
            serviceStateName: ENT_CANCELLED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@3be2d635
            eventId: 762e80db-d75e-4b67-9ccc-b816a00181b7
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: STOP_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: STOP_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

{
   "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
   "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
   "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
   "subscriptions":[
      {
         "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
         "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
         "subscriptionId":"e29573cc-d0e6-4d26-b97e-1a9c02d520ad",
         "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
         "startDate":"2013-08-01",
         "productName":"Sports",
         "productCategory":"BASE",
         "billingPeriod":"MONTHLY",
         "phaseType":"TRIAL",
         "priceList":"DEFAULT",
         "planName":"sports-monthly",
         "state":"ACTIVE",
         "sourceType":"NATIVE",
         "chargedThroughDate":"2013-08-01",
         "billingStartDate":"2013-08-01",
         "billCycleDayLocal":31,
         "events":[
            {
               "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"sports-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"sports-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-31",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"PHASE",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement+billing-service",
               "serviceStateName":"PHASE",
               "phase":"sports-monthly-evergreen",
               "auditLogs":[]
            }
         ],
         "priceOverrides":[
            {
               "planName":"sports-monthly",
               "phaseName":"sports-monthly-trial",
               "phaseType":"TRIAL",
               "fixedPrice":0
            },
            {
               "planName":"sports-monthly",
               "phaseName":"sports-monthly-evergreen",
               "phaseType":"EVERGREEN",
               "recurringPrice":500.0
            }
         ],
         "auditLogs":[]
      }
   ],
   "timeline":{
      "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
      "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
      "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
      "events":[
         {
            "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_ENTITLEMENT",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement-service",
            "serviceStateName":"ENT_STARTED",
            "phase":"sports-monthly-trial",
            "auditLogs":[]
         },
         {
            "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_BILLING",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"billing-service",
            "serviceStateName":"START_BILLING",
            "phase":"sports-monthly-trial",
            "auditLogs":[]
         },
         {
            "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-31",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"PHASE",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement+billing-service",
            "serviceStateName":"PHASE",
            "phase":"sports-monthly-evergreen",
            "auditLogs":[]
         }
      ],
      "auditLogs":[]
   },
   "auditLogs":[]
}

{'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
 'audit_logs': [],
 'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
 'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
 'subscriptions': [{'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
                    'audit_logs': [],
                    'bill_cycle_day_local': 6,
                    'billing_end_date': None,
                    'billing_period': 'MONTHLY',
                    'billing_start_date': datetime.date(2018, 5, 7),
                    'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
                    'cancelled_date': None,
                    'charged_through_date': None,
                    'events': [{'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '80ca6915-0293-4b1d-8bc6-b3c9fe1bee03',
                                'event_type': 'START_ENTITLEMENT',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement-service',
                                'service_state_name': 'ENT_STARTED'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': 'ce26b570-0a9f-463e-b65c-96a9fd67f124',
                                'event_type': 'START_BILLING',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'billing-service',
                                'service_state_name': 'START_BILLING'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 6, 6),
                                'event_id': 'c7af9fa3-5465-4e69-8a84-6977c711921c',
                                'event_type': 'PHASE',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-evergreen',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement+billing-service',
                                'service_state_name': 'PHASE'}],
                    'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
                    'phase_type': 'TRIAL',
                    'plan_name': 'standard-monthly',
                    'price_list': 'DEFAULT',
                    'price_overrides': [{'fixed_price': 0.0,
                                         'phase_name': 'standard-monthly-trial',
                                         'phase_type': 'TRIAL',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': None,
                                         'usage_price_overrides': []},
                                        {'fixed_price': None,
                                         'phase_name': 'standard-monthly-evergreen',
                                         'phase_type': 'EVERGREEN',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': 100.0,
                                         'usage_price_overrides': []}],
                    'product_category': 'BASE',
                    'product_name': 'Standard',
                    'source_type': 'NATIVE',
                    'start_date': datetime.date(2018, 5, 7),
                    'state': 'ACTIVE',
                    'subscription_id': '6f6cab9d-dfe0-4b89-9a09-b16055f72f5c'}],
 'timeline': {'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
              'audit_logs': [],
              'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
              'events': [{'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '80ca6915-0293-4b1d-8bc6-b3c9fe1bee03',
                          'event_type': 'START_ENTITLEMENT',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement-service',
                          'service_state_name': 'ENT_STARTED'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': 'ce26b570-0a9f-463e-b65c-96a9fd67f124',
                          'event_type': 'START_BILLING',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'billing-service',
                          'service_state_name': 'START_BILLING'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 6, 6),
                          'event_id': 'c7af9fa3-5465-4e69-8a84-6977c711921c',
                          'event_type': 'PHASE',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-evergreen',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement+billing-service',
                          'service_state_name': 'PHASE'}],
              'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'}}

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a bundle resource object.

Retrieve a bundle by external key

This API retrieves a bundle resource object based on its external key

HTTP Request

Retrieves the details information for the Bundle using its externalKey.

GET http://127.0.0.1:8080/1.0/kb/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/bundles?externalKey=2cd2f4b5-a1c0-42a7-924f-64c7b791332d"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

String externalKey = "93199";
Boolean includedDeleted = false; // Will not include deleted bundles

Bundles bundles = bundleApi.getBundleByKey(externalKey, 
                                           includedDeleted,
                                           AuditLevel.NONE,
                                           requestOptions);

external_key = '4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135'
included_deleted = false

bundle = KillBillClient::Model::Bundle.new
bundle.find_by_external_key(external_key, 
                            included_deleted, 
                            options)

bundleApi = killbill.api.BundleApi()
bundle_external_key = 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'

bundleApi.get_bundle_by_key(bundle_external_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

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

class Bundle {
    org.killbill.billing.client.model.gen.Bundle@2b6e1c9d
    accountId: a7c0b70d-fbc3-43cf-98e7-0af57c1a93fb
    bundleId: 4a2fcd90-7c8c-4877-93f9-9e99e8cd6953
    externalKey: 93199
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@22dc8662
        accountId: a7c0b70d-fbc3-43cf-98e7-0af57c1a93fb
        bundleId: 4a2fcd90-7c8c-4877-93f9-9e99e8cd6953
        subscriptionId: 9a55b6f3-ada7-4a78-915f-373af56cbb00
        externalKey: 93199
        startDate: 2012-04-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-04-25
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@ebe2ab4a
            eventId: 37b7e919-08ba-4c7d-a902-8d7a10b47157
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@9e770028
            eventId: 2a994af7-8faf-444f-a1df-fd6c68a9dbab
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@54e085c2
            eventId: 95ddcc14-ea6d-4a5c-b057-3a0d33341ab9
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: [class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePriceOverrides: []
        }, class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePriceOverrides: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@7ea930a8
        accountId: a7c0b70d-fbc3-43cf-98e7-0af57c1a93fb
        bundleId: 4a2fcd90-7c8c-4877-93f9-9e99e8cd6953
        externalKey: 93199
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@89e50f83
            eventId: 37b7e919-08ba-4c7d-a902-8d7a10b47157
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@cb989fa0
            eventId: 2a994af7-8faf-444f-a1df-fd6c68a9dbab
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@5fe74ae5
            eventId: 95ddcc14-ea6d-4a5c-b057-3a0d33341ab9
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

{
   "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
   "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
   "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
   "subscriptions":[
      {
         "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
         "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
         "subscriptionId":"e29573cc-d0e6-4d26-b97e-1a9c02d520ad",
         "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
         "startDate":"2013-08-01",
         "productName":"Sports",
         "productCategory":"BASE",
         "billingPeriod":"MONTHLY",
         "phaseType":"TRIAL",
         "priceList":"DEFAULT",
         "planName":"sports-monthly",
         "state":"ACTIVE",
         "sourceType":"NATIVE",
         "chargedThroughDate":"2013-08-01",
         "billingStartDate":"2013-08-01",
         "billCycleDayLocal":31,
         "events":[
            {
               "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"sports-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"sports-monthly-trial",
               "auditLogs":[]
            },
            {
               "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-08-31",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"PHASE",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement+billing-service",
               "serviceStateName":"PHASE",
               "phase":"sports-monthly-evergreen",
               "auditLogs":[]
            }
         ],
         "priceOverrides":[
            {
               "planName":"sports-monthly",
               "phaseName":"sports-monthly-trial",
               "phaseType":"TRIAL",
               "fixedPrice":0
            },
            {
               "planName":"sports-monthly",
               "phaseName":"sports-monthly-evergreen",
               "phaseType":"EVERGREEN",
               "recurringPrice":500.0
            }
         ],
         "auditLogs":[]
      }
   ],
   "timeline":{
      "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
      "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
      "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
      "events":[
         {
            "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_ENTITLEMENT",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement-service",
            "serviceStateName":"ENT_STARTED",
            "phase":"sports-monthly-trial",
            "auditLogs":[]
         },
         {
            "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_BILLING",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"billing-service",
            "serviceStateName":"START_BILLING",
            "phase":"sports-monthly-trial",
            "auditLogs":[]
         },
         {
            "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-08-31",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"PHASE",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement+billing-service",
            "serviceStateName":"PHASE",
            "phase":"sports-monthly-evergreen",
            "auditLogs":[]
         }
      ],
      "auditLogs":[]
   },
   "auditLogs":[]
}

{'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
 'audit_logs': [],
 'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
 'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
 'subscriptions': [{'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
                    'audit_logs': [],
                    'bill_cycle_day_local': 6,
                    'billing_end_date': None,
                    'billing_period': 'MONTHLY',
                    'billing_start_date': datetime.date(2018, 5, 7),
                    'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
                    'cancelled_date': None,
                    'charged_through_date': None,
                    'events': [{'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '80ca6915-0293-4b1d-8bc6-b3c9fe1bee03',
                                'event_type': 'START_ENTITLEMENT',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement-service',
                                'service_state_name': 'ENT_STARTED'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': 'ce26b570-0a9f-463e-b65c-96a9fd67f124',
                                'event_type': 'START_BILLING',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'billing-service',
                                'service_state_name': 'START_BILLING'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 6, 6),
                                'event_id': 'c7af9fa3-5465-4e69-8a84-6977c711921c',
                                'event_type': 'PHASE',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-evergreen',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement+billing-service',
                                'service_state_name': 'PHASE'}],
                    'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
                    'phase_type': 'TRIAL',
                    'plan_name': 'standard-monthly',
                    'price_list': 'DEFAULT',
                    'price_overrides': [{'fixed_price': 0.0,
                                         'phase_name': 'standard-monthly-trial',
                                         'phase_type': 'TRIAL',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': None,
                                         'usage_price_overrides': []},
                                        {'fixed_price': None,
                                         'phase_name': 'standard-monthly-evergreen',
                                         'phase_type': 'EVERGREEN',
                                         'plan_name': 'standard-monthly',
                                         'recurring_price': 100.0,
                                         'usage_price_overrides': []}],
                    'product_category': 'BASE',
                    'product_name': 'Standard',
                    'source_type': 'NATIVE',
                    'start_date': datetime.date(2018, 5, 7),
                    'state': 'ACTIVE',
                    'subscription_id': '6f6cab9d-dfe0-4b89-9a09-b16055f72f5c'}],
 'timeline': {'account_id': '8ef95bea-9306-4b26-a43c-090de8779599',
              'audit_logs': [],
              'bundle_id': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691',
              'events': [{'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '80ca6915-0293-4b1d-8bc6-b3c9fe1bee03',
                          'event_type': 'START_ENTITLEMENT',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement-service',
                          'service_state_name': 'ENT_STARTED'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': 'ce26b570-0a9f-463e-b65c-96a9fd67f124',
                          'event_type': 'START_BILLING',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'billing-service',
                          'service_state_name': 'START_BILLING'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 6, 6),
                          'event_id': 'c7af9fa3-5465-4e69-8a84-6977c711921c',
                          'event_type': 'PHASE',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-evergreen',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement+billing-service',
                          'service_state_name': 'PHASE'}],
              'external_key': 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'}}

Query Parameters

Name	Type	Required	Default	Description
externalKey	String	yes	none	The subscription external key
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a subscription resource object.

Update a bundle externalKey

THis API sets a new external key for a bundle

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/renameKey

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 '{ "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d", "externalKey": "another_external_key"}' \
    "http://127.0.0.1:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/renameKey"

TODO    

bundle = KillBillClient::Model::Bundle.new
bundle.bundle_id = bundle_id
bundle.external_key = "new_external_key"

bundle.rename_external_key(user, 
                           reason, 
                           comment, 
                           options)

bundleApi = killbill.api.BundleApi()
body = Bundle(bundle_id=bundle_id, 
              external_key='new_external_key')

bundleApi.rename_external_key(bundle_id,
                              body,
                              created_by,
                              api_key,
                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Request Body

A bundle resource containing the new external key

Query Parameters

None.

Response

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

Transfer

Transfer a bundle to another account.

Transfer a bundle to another account

This API "transfers" a bundle to another existing account. This is carried out as follows:

1. A new bundle is created in the destination account. The new bundle is assigned a new id but receives the same external key from the original bundle.

2. All subscriptions in the original bundle are copied to the new bundle. The sourceType of these subscriptions is set to TRANSFERRED.

3. All subscriptions in the original bundle are marked cancelled as of the transfer date but are not deleted. Billing is terminated on the transfer date or later according to the billing policy.

4. The subscriptions in the new bundle are assigned a start date as of the time of transfer, and inherit all of the terms and remaining dates from the original subscription.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}

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": "8785164f-b5d7-4da1-9495-33f5105e8d80", "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d"}' \
    "http://127.0.01:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("b84a8af9-73d4-4749-8d81-38dbcc2d7fb1");
UUID accountId = UUID.fromString("d82d3638-fca7-4c16-9e68-8f8db75997cc");

Bundle bundle = new Bundle();
bundle.setAccountId(accountId);
bundle.setBundleId(bundleId);

LocalDate requestedDate = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;
BillingActionPolicy billingPolicy = null;

Bundle result = bundleApi.transferBundle(bundleId, 
                                         bundle, 
                                         requestedDate, 
                                         billingPolicy,
                                         NULL_PLUGIN_PROPERTIES, 
                                         requestOptions);

requested_date = "2013-08-01"
billing_policy = "END_OF_TERM"

bundle = KillBillClient::Model::Bundle.new
bundle.account_id = new_account_id
bundle.bundle_id = bundle_id

bundle.transfer(requested_date, 
                billing_policy, 
                user, 
                reason, 
                comment, 
                options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'
new_account_id = '71499886-296d-4b0f-8b76-0eed352d8801'
body = Bundle(bundle_id=bundle_id, account_id=new_account_id)

bundleApi.transfer_bundle(bundle_id, 
                          body, 
                          created_by, 
                          api_key, 
                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d?billingPolicy=END_OF_TERM
< Content-Type: application/json
< Content-Length: 0

class Bundle {
    org.killbill.billing.client.model.gen.Bundle@222591c5
    accountId: d82d3638-fca7-4c16-9e68-8f8db75997cc
    bundleId: b84a8af9-73d4-4749-8d81-38dbcc2d7fb1
    externalKey: 93199
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@a668d933
        accountId: d82d3638-fca7-4c16-9e68-8f8db75997cc
        bundleId: b84a8af9-73d4-4749-8d81-38dbcc2d7fb1
        subscriptionId: 373e7cce-0558-4c31-98af-aab54b67c4a6
        externalKey: 93199
        startDate: 2012-04-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: TRANSFERRED
        cancelledDate: null
        chargedThroughDate: null
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@1e1bbe63
            eventId: 1779fcae-a6ca-43dd-9429-85f946fa4055
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@54887921
            eventId: b242eda1-dc26-4875-b92c-a99c76084a06
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@5652e31d
            eventId: 5b59caa3-d996-4c9c-afc1-cc932e5a0ff8
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: [class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-trial
            phaseType: TRIAL
            fixedPrice: 0
            recurringPrice: null
            usagePriceOverrides: []
        }, class PhasePriceOverride {
            planName: shotgun-monthly
            phaseName: shotgun-monthly-evergreen
            phaseType: EVERGREEN
            fixedPrice: null
            recurringPrice: 249.95
            usagePriceOverrides: []
        }]
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@8ad5adda
        accountId: d82d3638-fca7-4c16-9e68-8f8db75997cc
        bundleId: b84a8af9-73d4-4749-8d81-38dbcc2d7fb1
        externalKey: 93199
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@49f9e293
            eventId: 1779fcae-a6ca-43dd-9429-85f946fa4055
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@55e764b4
            eventId: b242eda1-dc26-4875-b92c-a99c76084a06
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@16aec25d
            eventId: 5b59caa3-d996-4c9c-afc1-cc932e5a0ff8
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

{
   "accountId":"71499886-296d-4b0f-8b76-0eed352d8801",
   "bundleId":"cff04ff5-19ba-4bdc-8aca-ed486d4b845c",
   "externalKey":"25f2de6b-2443-4d7c-8487-22bf6df5a5ec-73709",
   "subscriptions":[
      {
         "accountId":"71499886-296d-4b0f-8b76-0eed352d8801",
         "bundleId":"cff04ff5-19ba-4bdc-8aca-ed486d4b845c",
         "subscriptionId":"46e6fcdc-9f63-4ffc-a091-0cde70f964f0",
         "externalKey":"25f2de6b-2443-4d7c-8487-22bf6df5a5ec-73709",
         "startDate":"2013-09-01",
         "productName":"Sports",
         "productCategory":"BASE",
         "billingPeriod":"MONTHLY",
         "phaseType":"EVERGREEN",
         "priceList":"DEFAULT",
         "planName":"sports-monthly",
         "state":"ACTIVE",
         "sourceType":"TRANSFERRED",
         "billingStartDate":"2013-09-01",
         "billCycleDayLocal":1,
         "events":[
            {
               "eventId":"605c5696-4046-4597-8a67-7e50d26856cd",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-09-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_ENTITLEMENT",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"entitlement-service",
               "serviceStateName":"ENT_STARTED",
               "phase":"sports-monthly-evergreen",
               "auditLogs":[]
            },
            {
               "eventId":"fbc53e69-0683-4904-bc77-5d244b9ad1c9",
               "billingPeriod":"MONTHLY",
               "effectiveDate":"2013-09-01",
               "plan":"sports-monthly",
               "product":"Sports",
               "priceList":"DEFAULT",
               "eventType":"START_BILLING",
               "isBlockedBilling":false,
               "isBlockedEntitlement":false,
               "serviceName":"billing-service",
               "serviceStateName":"START_BILLING",
               "phase":"sports-monthly-evergreen",
               "auditLogs":[]
            }
         ],
         "priceOverrides":[
            {
               "planName":"sports-monthly",
               "phaseName":"sports-monthly-evergreen",
               "phaseType":"EVERGREEN",
               "recurringPrice":500.0
            }
         ],
         "auditLogs":[]
      }
   ],
   "timeline":{
      "accountId":"71499886-296d-4b0f-8b76-0eed352d8801",
      "bundleId":"cff04ff5-19ba-4bdc-8aca-ed486d4b845c",
      "externalKey":"25f2de6b-2443-4d7c-8487-22bf6df5a5ec-73709",
      "events":[
         {
            "eventId":"605c5696-4046-4597-8a67-7e50d26856cd",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-09-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_ENTITLEMENT",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement-service",
            "serviceStateName":"ENT_STARTED",
            "phase":"sports-monthly-evergreen",
            "auditLogs":[]
         },
         {
            "eventId":"fbc53e69-0683-4904-bc77-5d244b9ad1c9",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2013-09-01",
            "plan":"sports-monthly",
            "product":"Sports",
            "priceList":"DEFAULT",
            "eventType":"START_BILLING",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"billing-service",
            "serviceStateName":"START_BILLING",
            "phase":"sports-monthly-evergreen",
            "auditLogs":[]
         }
      ],
      "auditLogs":[]
   },
   "auditLogs":[]
}

no content

Request Body

A bundle resource containing the new account id

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	Requested date for the transfer of the bundle
billingPolicy	string	no	IMMEDIATE	When billing should occur (see below)

billingPolicy: options are START_OF_TERM, END_OF_TERM, or IMMEDIATE.

Response

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

Blocking State

See section Account Blocking State for an introduction.

Pause a bundle

Provides a simple interface to pause both billing and entitlement for all subscriptions in a bundle. The state attribute in the bundle resource is set to BLOCKED.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/pause

Example Request:

  -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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/pause" \

TODO    

bundle = KillBillClient::Model::Bundle.new
bundle.bundle_id = bundle_id
requested_date = "2013-08-01"

bundle.pause(requested_date, 
             user, 
             reason, 
             comment, 
             options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'ce967207-851c-4040-bfbd-74a8924f9b8a'

bundleApi.pause_bundle(bundle_id, 
                       created_by, 
                       api_key, 
                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	requested date for pausing

Response

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

Resume a bundle

Provides a simple interface to resume both billing and entitlement for all subscriptions in the bundle. The state of the bundle resource is set to ACTIVE.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/resume

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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/resume"

TODO    

bundle = KillBillClient::Model::Bundle.new
bundle.bundle_id = bundle_id
requested_date = "2013-08-01"

bundle.resume(requested_date, 
              user, 
              reason, 
              comment, 
              options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'ce967207-851c-4040-bfbd-74a8924f9b8a'

bundleApi.resume_bundle(bundle_id, 
                        created_by, 
                        api_key, 
                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	requested date to resume

Response

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

Block a bundle

Provides a low level interface to add a BlockingState event for this bundle. Note that the previous pause and resume operations can be achieved using this API.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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, "effectiveDate": "2018-07-17T21:17:28.842Z", "type": "SUBSCRIPTION" }' \
    "http://127.0.0.1:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/block"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("b84a8af9-73d4-4749-8d81-38dbcc2d7fb1");

String stateName = "block";
String service = "service";
Boolean isBlockChange = false;
Boolean isBlockEntitlement = true;
Boolean isBlockBilling = true;
DateTime effectiveDate = null;
List<AuditLog> auditLogs = null;

BlockingState blockingState = new BlockingState(bundleId, 
                                                stateName, 
                                                service, 
                                                isBlockChange, 
                                                isBlockEntitlement, 
                                                isBlockBilling, 
                                                effectiveDate, 
                                                BlockingStateType.SUBSCRIPTION_BUNDLE, 
                                                auditLogs);

LocalDate requestedDate = clock.getToday(DateTimeZone.forID(account.getTimeZone()));
Map<String, String> pluginProperty = ImmutableMap.<String, String>of();

bundleApi.addBundleBlockingState(bundleId, 
                                 blockingState, 
                                 requestedDate, 
                                 pluginProperty, 
                                 requestOptions);

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

bundle.set_blocking_state(state_name,
                          service,
                          block_change, 
                          block_entitlement,
                          block_billing, 
                          requested_date,
                          user, 
                          reason, 
                          comment,
                          options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'a760fdc8-1e2d-4020-918a-6e4f7a9cd691'
body = BlockingState(state_name='STATE1', 
                     service='ServiceStateService', 
                     is_block_change=False, 
                     is_block_entitlement=False, 
                     is_block_billing=False)

bundleApi.add_bundle_blocking_state(bundle_id,
                                    body,
                                    created_by,
                                    api_key,
                                    api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/accounts/2ad52f53-85ae-408a-9879-32a7e59dd03d/block?blockingStateTypes=SUBSCRIPTION_BUNDLE
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Request Body

A blocking state resource representing the intended new blocking state. For example,

{ "blockedId": "943c4fd0-9000-4975-a3a8-09712223e1f8",
"stateName": "STATE1",
"service": "ServiceStateService",
"isBlockChange": false,
"isBlockEntitlement": false,
"isBlockBilling": true, "effectiveDate": "2020-07-18T18:22:30.376Z", "type": "SUBSCRIPTION_BUNDLE" }

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	immediate	requested date for blocking

Response

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

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resources. For more on custom fields see Custom Fields. These endpoints manage custom fields associated with Bundle objects.

Add custom fields to bundle

Adds one or more custom fields to a subscription object. Existing custom fields are not disturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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": "BUNDLE", "name": "Test Custom Field", "value": "demo_test_value" }]' \
    "http://127.0.0.1:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("b84a8af9-73d4-4749-8d81-38dbcc2d7fb1");
final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

bundleApi.createBundleCustomFields(bundleId, 
                                   customFields, 
                                   requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'BUNDLE'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

bundle.add_custom_field(custom_field, 
                        user,
                        reason,
                        comment,
                        options)

bundleApi = killbill.api.BundleApi()
body = CustomField(name='Test Custom Field', value='test_value')

bundleApi.create_bundle_custom_fields(bundle_id,
                                      [body],
                                      created_by,
                                      api_key,
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: BUNDLE
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"6e571e22-b794-413c-be6f-1b2aa4bf9824",
      "objectId":"0149ffc6-fdfd-40b1-8cf4-29a66aef51d4",
      "objectType":"BUNDLE",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

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 status code of 201 and an empty body.

Retrieve bundle custom fields

Retrieves any custom field objects associated with the specified bundle

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/customFields

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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

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

List<CustomField> bundleCustomFields = bundleApi.getBundleCustomFields(bundleId,
                                                                       AuditLevel.NONE,
                                                                       requestOptions);

audit = 'NONE'

bundle.custom_fields(audit, options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'ce967207-851c-4040-bfbd-74a8924f9b8a'

bundleApi.get_bundle_custom_fields(bundle_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "customFieldId": "349de10f-4bb1-4e1a-93f6-11b745200bf5",
    "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "objectType": "BUNDLE",
    "name": "Test Custom Field",
    "value": "demo_test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: BUNDLE
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"BUNDLE",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '5670b594-9317-4aeb-bfef-2c2342ec172a',
 'name': 'Test Custom Field',
 'object_id': 'ce967207-851c-4040-bfbd-74a8924f9b8a',
 'object_type': 'BUNDLE',
 'value': 'test_value'}]

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for a bundle

Modifies the value of one or more existing custom fields associated with a bundle

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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": "349de10f-4bb1-4e1a-93f6-11b745200bf5", "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d", "objectType": "BUNDLE", "name": "Test Custom Field", "value": "test_modify_value", "auditLogs": [] }]' \
    "http://127.0.0.1:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = 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");

bundleApi.modifyBundleCustomFields(bundleId, 
                                   customFieldModified, 
                                   requestOptions);

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

bundle.modify_custom_field(custom_field,                                                                                            
                           user, 
                           reason,
                           comment, 
                           options)

bundleApi = killbill.api.BundleApi()
body = CustomField(custom_field_id=custom_field_id, 
                   name='Test Custom Field', 
                   value='test_value')

bundleApi.modify_bundle_custom_fields(bundle_id, 
                                      [body], 
                                      created_by, 
                                      api_key, 
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Remove custom fields from bundle

Delete one or more custom fields from a bundle

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/customFields

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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields?customField=349de10f-4bb1-4e1a-93f6-11b745200bf5"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

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

bundleApi.deleteBundleCustomFields(bundleId, 
                                   customFieldsId, 
                                   requestOptions);

custom_field_id = custom_field.id

bundle.remove_custom_field(custom_field_id, 
                           user, 
                           reason,
                           comment, 
                           options)

bundleApi = killbill.api.BundleApi()
bundle_id = 'ce967207-851c-4040-bfbd-74a8924f9b8a' 

bundleApi.delete_bundle_custom_fields(bundle_id, 
                                      created_by, 
                                      api_key, 
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	none	List of object IDs for the custom fields that should be deleted.

Response

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

Tags

See section Account Tags for an introduction.

The are no system tags applicable for a Bundle.

Let's assume there is an existing user tagDefintion already created with tagDefinitionId=353752dd-9041-4450-b782-a8bb03a923c8.

Add tags to bundle

This API adds one or more tags to a subscription. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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 '[ "353752dd-9041-4450-b782-a8bb03a923c8"]' \
    "http://127.0.0.1:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

Tags result = bundleApi.createBundleTags(bundleId, 
                                         ImmutableList.<UUID>of(tagDefinitionId), 
                                         requestOptions);

tag_name = 'foo'

bundle.add_tag(tag_name,
               user,
               reason,
               comment,
               options)

bundleApi = killbill.api.BundleApi()
bundle_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

bundleApi.create_bundle_tags(bundle_id, 
                             tag, 
                             created_by, 
                             api_key, 
                             api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: BUNDLE
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"BUNDLE",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[

      ]
   }
]

no content

Request Body

A JSON array containing one or more strings giving the UUID of tag definitions for the user tags to be added.

Query Parameters

None.

Returns

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

Retrieve bundle tags

Retrieve all tags attached to this bundle.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");
Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags1 = bundleApi.getBundleTags(bundleId, 
                                          includedDeleted, 
                                          AuditLevel.FULL, 
                                          requestOptions);

included_deleted = false
audit = 'NONE'

bundle.tags(included_deleted,
            audit,
            options)

bundleApi = killbill.api.BundleApi()
bundle_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

bundleApi.get_bundle_tags(bundle_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "tagId": "e054c84a-0518-4611-92a8-53e849f0affd",
    "objectType": "BUNDLE",
    "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "tagDefinitionId": "353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName": "foo",
    "auditLogs": []
  }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: BUNDLE
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"BUNDLE",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[

      ]
   }
]

[{'audit_logs': [],
 'object_id': '3e94fccf-0f37-40aa-90a4-122a4f381ebc',
 'object_type': 'BUNDLE',
 'tag_definition_id': '353752dd-9041-4450-b782-a8bb03a923c8',
 'tag_definition_name': 'foo',
 'tag_id': 'fc7fab6e-751c-4dd3-b7fa-e93a66e42822'}]

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted tags
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from bundle

This API removes a list of tags attached to a bundle.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/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/bundles/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

UUID bundleId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

bundleApi.deleteBundleTags(bundleId, 
                           ImmutableList.<UUID>of(tagDefinitionId), 
                           requestOptions);

tag_name = 'foo'

bundle.remove_tag(tag_name,
                  user,
                  reason,
                  comment,
                  options)

bundleApi = killbill.api.BundleApi()
bundle_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

bundleApi.delete_bundle_tags(bundle_id, 
                             created_by, 
                             api_key, 
                             api_secret,
                             tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of strings	true	none	List of tag definition IDs identifying the tags that should be removed.

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 bundle audit logs with history by bundle id

Retrieve a list of audit log records showing events that occurred involving changes to the bundle. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/bundles/{bundleId}/auditLogsWithHistory

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/bundles/d1b329c7-7dcf-466c-aaca-47bff304dab0/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json
[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "BUNDLE",
    "objectId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
    "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": 316,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "externalKey": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "accountId": "7b3e14b1-6e76-46d3-bbfd-5a16e5b5eca2",
      "lastSysUpdateDate": "2019-02-22T22:38:10.000Z",
      "originalCreatedDate": "2019-02-22T22:38:10.000Z",
      "tableName": "BUNDLES",
      "historyTableName": "BUNDLE_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "BUNDLE",
    "objectId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
    "changedBy": "SubscriptionBaseTransition",
    "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": 316,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "externalKey": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "accountId": "7b3e14b1-6e76-46d3-bbfd-5a16e5b5eca2",
      "lastSysUpdateDate": "2019-02-22T22:38:10.000Z",
      "originalCreatedDate": "2019-02-22T22:38:10.000Z",
      "tableName": "BUNDLES",
      "historyTableName": "BUNDLE_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

List/Search

List bundles

HTTP Request

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

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/bundles/pagination"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

Long offset = 0L;
Long limit = 1L;

Bundles allBundles = bundleApi.getBundles(offset, 
                                          limit, 
                                          AuditLevel.NONE, 
                                          requestOptions);

offset = 0
limit = 100

bundle.find_in_batches(offset,
                       limit,
                       options)

bundleApi = killbill.api.BundleApi()

bundleApi.get_bundles(api_key, api_secret,)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "externalKey": "another_external_key",
    "subscriptions": [
      {
        "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
        "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
        "externalKey": "another_external_key",
        "startDate": "2018-07-18",
        "productName": "Standard",
        "productCategory": "BASE",
        "billingPeriod": "MONTHLY",
        "phaseType": "TRIAL",
        "priceList": "DEFAULT",
        "planName": "standard-monthly",
        "state": "CANCELLED",
        "sourceType": "NATIVE",
        "cancelledDate": "2018-07-19",
        "chargedThroughDate": null,
        "billingStartDate": "2018-07-18",
        "billingEndDate": "2018-07-19",
        "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": "01387e92-8b6c-4c74-811f-3d2698646049",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "STOP_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": true,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_CANCELLED",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "1d605f2d-e605-47d5-b55c-904a0cba12f8",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "STOP_BILLING",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "billing-service",
            "serviceStateName": "STOP_BILLING",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "e9f343aa-3650-4709-a09d-8a3df908bd47",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "SERVICE_STATE_CHANGE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "ServiceStateService",
            "serviceStateName": "STATE1",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          }
        ],
        "priceOverrides": null,
        "prices": [],
        "auditLogs": []
      }
    ],
    "timeline": {
      "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "externalKey": "another_external_key",
      "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": "01387e92-8b6c-4c74-811f-3d2698646049",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "STOP_ENTITLEMENT",
          "isBlockedBilling": false,
          "isBlockedEntitlement": true,
          "serviceName": "entitlement-service",
          "serviceStateName": "ENT_CANCELLED",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "1d605f2d-e605-47d5-b55c-904a0cba12f8",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "STOP_BILLING",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "billing-service",
          "serviceStateName": "STOP_BILLING",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "e9f343aa-3650-4709-a09d-8a3df908bd47",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "SERVICE_STATE_CHANGE",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "ServiceStateService",
          "serviceStateName": "STATE1",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        }
      ],
      "auditLogs": []
    },
    "auditLogs": []
  },
  {
    "accountId": "8785164f-b5d7-4da1-9495-33f5105e8d80",
    "bundleId": "02134ca5-8254-4c73-aaf2-89ed99a28fce",
    "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "subscriptions": [
      {
        "accountId": "8785164f-b5d7-4da1-9495-33f5105e8d80",
        "bundleId": "02134ca5-8254-4c73-aaf2-89ed99a28fce",
        "subscriptionId": "3b78a8c1-30fb-4b4e-a247-b131cbf6fa71",
        "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "startDate": "2018-07-19",
        "productName": "Standard",
        "productCategory": "BASE",
        "billingPeriod": "MONTHLY",
        "phaseType": "TRIAL",
        "priceList": "DEFAULT",
        "planName": "standard-monthly",
        "state": "ACTIVE",
        "sourceType": "TRANSFERRED",
        "cancelledDate": null,
        "chargedThroughDate": "2018-07-19",
        "billingStartDate": "2018-07-19",
        "billingEndDate": null,
        "billCycleDayLocal": 18,
        "events": [
          {
            "eventId": "f247597d-deac-468e-8b18-9a04c633ec71",
            "billingPeriod": null,
            "effectiveDate": "2018-07-19",
            "plan": null,
            "product": null,
            "priceList": null,
            "eventType": "SERVICE_STATE_CHANGE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "account-service",
            "serviceStateName": "CLOSE_ACCOUNT",
            "phase": null,
            "auditLogs": []
          },
          {
            "eventId": "15987747-2c28-4475-965c-3b1cff08faa9",
            "billingPeriod": null,
            "effectiveDate": "2018-07-19",
            "plan": null,
            "product": null,
            "priceList": null,
            "eventType": "START_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_STARTED",
            "phase": null,
            "auditLogs": []
          },
          {
            "eventId": "51c53d93-d3c1-4906-b295-c5a1b0d761e7",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "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": "2cf6cd36-d0d1-461b-b525-f2a36a73be76",
            "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": [],
        "auditLogs": []
      }
    ],
    "timeline": {
      "accountId": "8785164f-b5d7-4da1-9495-33f5105e8d80",
      "bundleId": "02134ca5-8254-4c73-aaf2-89ed99a28fce",
      "externalKey": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "events": [
        {
          "eventId": "f247597d-deac-468e-8b18-9a04c633ec71",
          "billingPeriod": null,
          "effectiveDate": "2018-07-19",
          "plan": null,
          "product": null,
          "priceList": null,
          "eventType": "SERVICE_STATE_CHANGE",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "account-service",
          "serviceStateName": "CLOSE_ACCOUNT",
          "phase": null,
          "auditLogs": []
        },
        {
          "eventId": "15987747-2c28-4475-965c-3b1cff08faa9",
          "billingPeriod": null,
          "effectiveDate": "2018-07-19",
          "plan": null,
          "product": null,
          "priceList": null,
          "eventType": "START_ENTITLEMENT",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "entitlement-service",
          "serviceStateName": "ENT_STARTED",
          "phase": null,
          "auditLogs": []
        },
        {
          "eventId": "51c53d93-d3c1-4906-b295-c5a1b0d761e7",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "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": "2cf6cd36-d0d1-461b-b525-f2a36a73be76",
          "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": []
  }
]

//First element of the list
class Bundle {
    org.killbill.billing.client.model.gen.Bundle@2659bf49
    accountId: b99980fb-331f-4129-834b-3522e845a4e3
    bundleId: b424e3d6-d747-4309-954d-1acb41bc690c
    externalKey: 757e352e-dd97-4800-93a8-d2c38e407140
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@ec70e97d
        accountId: b99980fb-331f-4129-834b-3522e845a4e3
        bundleId: b424e3d6-d747-4309-954d-1acb41bc690c
        subscriptionId: bacec1ee-7815-485f-bec2-0a875a8d68ad
        externalKey: 757e352e-dd97-4800-93a8-d2c38e407140
        startDate: 2012-08-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-08-25
        billingStartDate: 2012-08-25
        billingEndDate: null
        billCycleDayLocal: 24
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@324b0f94
            eventId: 9b35680c-c63c-47c8-9fe5-671b4bfa4e69
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@a1eefba7
            eventId: b24494ca-755c-4432-8b21-6923d5fdd30f
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@66e2bfa7
            eventId: a306143d-d2a3-4f72-95c8-91b97ee7e6ca
            billingPeriod: MONTHLY
            effectiveDate: 2012-09-24
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: []
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@d6ec82ea
        accountId: b99980fb-331f-4129-834b-3522e845a4e3
        bundleId: b424e3d6-d747-4309-954d-1acb41bc690c
        externalKey: 757e352e-dd97-4800-93a8-d2c38e407140
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@43676058
            eventId: 9b35680c-c63c-47c8-9fe5-671b4bfa4e69
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@2e29a294
            eventId: b24494ca-755c-4432-8b21-6923d5fdd30f
            billingPeriod: MONTHLY
            effectiveDate: 2012-08-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@9c578f29
            eventId: a306143d-d2a3-4f72-95c8-91b97ee7e6ca
            billingPeriod: MONTHLY
            effectiveDate: 2012-09-24
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

[
  {
     "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
     "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
     "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
     "subscriptions":[
        {
           "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
           "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
           "subscriptionId":"e29573cc-d0e6-4d26-b97e-1a9c02d520ad",
           "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
           "startDate":"2013-08-01",
           "productName":"Sports",
           "productCategory":"BASE",
           "billingPeriod":"MONTHLY",
           "phaseType":"TRIAL",
           "priceList":"DEFAULT",
           "planName":"sports-monthly",
           "state":"ACTIVE",
           "sourceType":"NATIVE",
           "chargedThroughDate":"2013-08-01",
           "billingStartDate":"2013-08-01",
           "billCycleDayLocal":31,
           "events":[
              {
                 "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-01",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"START_ENTITLEMENT",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"entitlement-service",
                 "serviceStateName":"ENT_STARTED",
                 "phase":"sports-monthly-trial",
                 "auditLogs":[]
              },
              {
                 "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-01",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"START_BILLING",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"billing-service",
                 "serviceStateName":"START_BILLING",
                 "phase":"sports-monthly-trial",
                 "auditLogs":[]
              },
              {
                 "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-31",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"PHASE",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"entitlement+billing-service",
                 "serviceStateName":"PHASE",
                 "phase":"sports-monthly-evergreen",
                 "auditLogs":[]
              }
           ],
           "priceOverrides":[
              {
                 "planName":"sports-monthly",
                 "phaseName":"sports-monthly-trial",
                 "phaseType":"TRIAL",
                 "fixedPrice":0
              },
              {
                 "planName":"sports-monthly",
                 "phaseName":"sports-monthly-evergreen",
                 "phaseType":"EVERGREEN",
                 "recurringPrice":500.0
              }
           ],
           "auditLogs":[]
        }
     ],
     "timeline":{
        "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
        "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
        "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
        "events":[
           {
              "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-01",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"START_ENTITLEMENT",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"entitlement-service",
              "serviceStateName":"ENT_STARTED",
              "phase":"sports-monthly-trial",
              "auditLogs":[]
           },
           {
              "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-01",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"START_BILLING",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"billing-service",
              "serviceStateName":"START_BILLING",
              "phase":"sports-monthly-trial",
              "auditLogs":[]
           },
           {
              "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-31",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"PHASE",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"entitlement+billing-service",
              "serviceStateName":"PHASE",
              "phase":"sports-monthly-evergreen",
              "auditLogs":[]
           }
        ],
        "auditLogs":[]
     },
     "auditLogs":[]
  }
]

[{'account_id': '7c86f63a-3380-4487-99e1-1865108a3e6c',
 'audit_logs': [],
 'bundle_id': 'e700381c-3af4-479a-af92-485c5ac89e41',
 'external_key': 'e700381c-3af4-479a-af92-485c5ac89e41',
 'subscriptions': [{'account_id': '7c86f63a-3380-4487-99e1-1865108a3e6c',
                    'audit_logs': [],
                    'bill_cycle_day_local': 6,
                    'billing_end_date': None,
                    'billing_period': 'MONTHLY',
                    'billing_start_date': datetime.date(2018, 5, 7),
                    'bundle_id': 'e700381c-3af4-479a-af92-485c5ac89e41',
                    'cancelled_date': None,
                    'charged_through_date': None,
                    'events': [{'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '3639baf9-57a5-4c52-92da-d13432b48919',
                                'event_type': 'START_ENTITLEMENT',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement-service',
                                'service_state_name': 'ENT_STARTED'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '2b3efee7-6cb5-4801-8abd-c11936b69439',
                                'event_type': 'START_BILLING',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'billing-service',
                                'service_state_name': 'START_BILLING'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 6, 6),
                                'event_id': '2dbbf736-1c24-42f7-83fc-fbc2a8059e96',
                                'event_type': 'PHASE',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-evergreen',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement+billing-service',
                                'service_state_name': 'PHASE'}],
                    'external_key': 'e700381c-3af4-479a-af92-485c5ac89e41',
                    'phase_type': 'TRIAL',
                    'plan_name': 'standard-monthly',
                    'price_list': 'DEFAULT',
                    'price_overrides': [],
                    'product_category': 'BASE',
                    'product_name': 'Standard',
                    'source_type': 'NATIVE',
                    'start_date': datetime.date(2018, 5, 7),
                    'state': 'ACTIVE',
                    'subscription_id': '5ce4f7e1-5f82-4b6b-8ff6-a25ff64e7bdd'}],
 'timeline': {'account_id': '7c86f63a-3380-4487-99e1-1865108a3e6c',
              'audit_logs': [],
              'bundle_id': 'e700381c-3af4-479a-af92-485c5ac89e41',
              'events': [{'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '3639baf9-57a5-4c52-92da-d13432b48919',
                          'event_type': 'START_ENTITLEMENT',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement-service',
                          'service_state_name': 'ENT_STARTED'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '2b3efee7-6cb5-4801-8abd-c11936b69439',
                          'event_type': 'START_BILLING',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'billing-service',
                          'service_state_name': 'START_BILLING'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 6, 6),
                          'event_id': '2dbbf736-1c24-42f7-83fc-fbc2a8059e96',
                          'event_type': 'PHASE',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-evergreen',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement+billing-service',
                          'service_state_name': 'PHASE'}],
              'external_key': 'e700381c-3af4-479a-af92-485c5ac89e41'}}]

Query Parameters

Name	Type	Required	Default	Description
offset	long	no	0	Starting index for items listed
limit	long	no	100	maximum number of items listed
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Search bundles

Search for a bundle by a specified search string. The search string is compared to the accountId, the bundleId, and the bundle externalKey. The operation returns all bundle resources in which the search string matches any one of these attributes. Note: the string must match the entire attribute, not just a part of it.

HTTP Request

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

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/bundles/search/another_external_key"

import org.killbill.billing.client.api.gen.BundleApi;
protected BundleApi bundleApi;

String searchKey = "93199";
Long offset = 0L;
Long limit = 1L;

Bundles result = bundleApi.searchBundles(searchKey, 
                                         offset, 
                                         limit, 
                                         AuditLevel.NONE, 
                                         requestOptions);

search_key = 'example'
offset = 0
limit = 100

bundle.find_in_batches_by_search_key(search_key,
                                     offset,
                                     limit,
                                     options)

bundleApi = killbill.api.BundleApi()
search_key = '7b26b0ce-a495-4c0c-9dd5-11a556f03e8c'

bundleApi.search_bundles(search_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "externalKey": "another_external_key",
    "subscriptions": [
      {
        "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
        "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
        "subscriptionId": "8ab101b6-15e8-433b-b4f7-f99eeaa56a77",
        "externalKey": "another_external_key",
        "startDate": "2018-07-18",
        "productName": "Standard",
        "productCategory": "BASE",
        "billingPeriod": "MONTHLY",
        "phaseType": "TRIAL",
        "priceList": "DEFAULT",
        "planName": "standard-monthly",
        "state": "CANCELLED",
        "sourceType": "NATIVE",
        "cancelledDate": "2018-07-19",
        "chargedThroughDate": null,
        "billingStartDate": "2018-07-18",
        "billingEndDate": "2018-07-19",
        "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": "01387e92-8b6c-4c74-811f-3d2698646049",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "STOP_ENTITLEMENT",
            "isBlockedBilling": false,
            "isBlockedEntitlement": true,
            "serviceName": "entitlement-service",
            "serviceStateName": "ENT_CANCELLED",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "1d605f2d-e605-47d5-b55c-904a0cba12f8",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "STOP_BILLING",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "billing-service",
            "serviceStateName": "STOP_BILLING",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          },
          {
            "eventId": "e9f343aa-3650-4709-a09d-8a3df908bd47",
            "billingPeriod": "MONTHLY",
            "effectiveDate": "2018-07-19",
            "plan": "standard-monthly",
            "product": "Standard",
            "priceList": "DEFAULT",
            "eventType": "SERVICE_STATE_CHANGE",
            "isBlockedBilling": false,
            "isBlockedEntitlement": false,
            "serviceName": "ServiceStateService",
            "serviceStateName": "STATE1",
            "phase": "standard-monthly-trial",
            "auditLogs": []
          }
        ],
        "priceOverrides": null,
        "prices": [],
        "auditLogs": []
      }
    ],
    "timeline": {
      "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
      "bundleId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
      "externalKey": "another_external_key",
      "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": "01387e92-8b6c-4c74-811f-3d2698646049",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "STOP_ENTITLEMENT",
          "isBlockedBilling": false,
          "isBlockedEntitlement": true,
          "serviceName": "entitlement-service",
          "serviceStateName": "ENT_CANCELLED",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "1d605f2d-e605-47d5-b55c-904a0cba12f8",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "STOP_BILLING",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "billing-service",
          "serviceStateName": "STOP_BILLING",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        },
        {
          "eventId": "e9f343aa-3650-4709-a09d-8a3df908bd47",
          "billingPeriod": "MONTHLY",
          "effectiveDate": "2018-07-19",
          "plan": "standard-monthly",
          "product": "Standard",
          "priceList": "DEFAULT",
          "eventType": "SERVICE_STATE_CHANGE",
          "isBlockedBilling": false,
          "isBlockedEntitlement": false,
          "serviceName": "ServiceStateService",
          "serviceStateName": "STATE1",
          "phase": "standard-monthly-trial",
          "auditLogs": []
        }
      ],
      "auditLogs": []
    },
    "auditLogs": []
  }
]

//First element of the list
class Bundle {
    org.killbill.billing.client.model.gen.Bundle@6c335adf
    accountId: 132f0ce0-b3ae-4e49-90fd-b265ae8515b6
    bundleId: 23a23ae2-5b41-4b88-a731-98cb6f6f3f21
    externalKey: 93199
    subscriptions: [class Subscription {
        org.killbill.billing.client.model.gen.Subscription@30aa99f
        accountId: 132f0ce0-b3ae-4e49-90fd-b265ae8515b6
        bundleId: 23a23ae2-5b41-4b88-a731-98cb6f6f3f21
        subscriptionId: bc39131f-538d-406c-96f2-38db68dd328a
        externalKey: 93199
        startDate: 2012-04-25
        productName: Shotgun
        productCategory: BASE
        billingPeriod: MONTHLY
        phaseType: TRIAL
        priceList: DEFAULT
        planName: shotgun-monthly
        state: ACTIVE
        sourceType: NATIVE
        cancelledDate: null
        chargedThroughDate: 2012-04-25
        billingStartDate: 2012-04-25
        billingEndDate: null
        billCycleDayLocal: 25
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@850eec8c
            eventId: 03b54e77-da03-4efb-823c-03d4a42557f4
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@c9d2600
            eventId: 81afc2cd-ac13-4b48-86c9-920443291ff7
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@e7c34c4e
            eventId: 0bd9e27d-50fe-4144-9b52-01a0964d2306
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        priceOverrides: []
        auditLogs: []
    }]
    timeline: class BundleTimeline {
        org.killbill.billing.client.model.gen.BundleTimeline@92a9f4c7
        accountId: 132f0ce0-b3ae-4e49-90fd-b265ae8515b6
        bundleId: 23a23ae2-5b41-4b88-a731-98cb6f6f3f21
        externalKey: 93199
        events: [class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@9fa4b25a
            eventId: 03b54e77-da03-4efb-823c-03d4a42557f4
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_ENTITLEMENT
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement-service
            serviceStateName: ENT_STARTED
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@77fd66a
            eventId: 81afc2cd-ac13-4b48-86c9-920443291ff7
            billingPeriod: MONTHLY
            effectiveDate: 2012-04-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: START_BILLING
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: billing-service
            serviceStateName: START_BILLING
            phase: shotgun-monthly-trial
            auditLogs: []
        }, class EventSubscription {
            org.killbill.billing.client.model.gen.EventSubscription@b5670810
            eventId: 0bd9e27d-50fe-4144-9b52-01a0964d2306
            billingPeriod: MONTHLY
            effectiveDate: 2012-05-25
            plan: shotgun-monthly
            product: Shotgun
            priceList: DEFAULT
            eventType: PHASE
            isBlockedBilling: false
            isBlockedEntitlement: false
            serviceName: entitlement+billing-service
            serviceStateName: PHASE
            phase: shotgun-monthly-evergreen
            auditLogs: []
        }]
        auditLogs: []
    }
    auditLogs: []
}

[
  {
     "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
     "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
     "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
     "subscriptions":[
        {
           "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
           "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
           "subscriptionId":"e29573cc-d0e6-4d26-b97e-1a9c02d520ad",
           "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
           "startDate":"2013-08-01",
           "productName":"Sports",
           "productCategory":"BASE",
           "billingPeriod":"MONTHLY",
           "phaseType":"TRIAL",
           "priceList":"DEFAULT",
           "planName":"sports-monthly",
           "state":"ACTIVE",
           "sourceType":"NATIVE",
           "chargedThroughDate":"2013-08-01",
           "billingStartDate":"2013-08-01",
           "billCycleDayLocal":31,
           "events":[
              {
                 "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-01",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"START_ENTITLEMENT",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"entitlement-service",
                 "serviceStateName":"ENT_STARTED",
                 "phase":"sports-monthly-trial",
                 "auditLogs":[]
              },
              {
                 "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-01",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"START_BILLING",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"billing-service",
                 "serviceStateName":"START_BILLING",
                 "phase":"sports-monthly-trial",
                 "auditLogs":[]
              },
              {
                 "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
                 "billingPeriod":"MONTHLY",
                 "effectiveDate":"2013-08-31",
                 "plan":"sports-monthly",
                 "product":"Sports",
                 "priceList":"DEFAULT",
                 "eventType":"PHASE",
                 "isBlockedBilling":false,
                 "isBlockedEntitlement":false,
                 "serviceName":"entitlement+billing-service",
                 "serviceStateName":"PHASE",
                 "phase":"sports-monthly-evergreen",
                 "auditLogs":[]
              }
           ],
           "priceOverrides":[
              {
                 "planName":"sports-monthly",
                 "phaseName":"sports-monthly-trial",
                 "phaseType":"TRIAL",
                 "fixedPrice":0
              },
              {
                 "planName":"sports-monthly",
                 "phaseName":"sports-monthly-evergreen",
                 "phaseType":"EVERGREEN",
                 "recurringPrice":500.0
              }
           ],
           "auditLogs":[]
        }
     ],
     "timeline":{
        "accountId":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995",
        "bundleId":"5b7a5f2d-4054-412f-b354-b722c2cff4ec",
        "externalKey":"4b67f7d8-d7db-4e4f-b282-eb1cdf43a995-43135",
        "events":[
           {
              "eventId":"e0136144-a852-4eaa-b721-c8b585dcb4a6",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-01",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"START_ENTITLEMENT",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"entitlement-service",
              "serviceStateName":"ENT_STARTED",
              "phase":"sports-monthly-trial",
              "auditLogs":[]
           },
           {
              "eventId":"72a51773-9e1d-4ad7-beeb-03139f60ea3d",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-01",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"START_BILLING",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"billing-service",
              "serviceStateName":"START_BILLING",
              "phase":"sports-monthly-trial",
              "auditLogs":[]
           },
           {
              "eventId":"341992e2-4565-4457-9d20-d2803d11aa61",
              "billingPeriod":"MONTHLY",
              "effectiveDate":"2013-08-31",
              "plan":"sports-monthly",
              "product":"Sports",
              "priceList":"DEFAULT",
              "eventType":"PHASE",
              "isBlockedBilling":false,
              "isBlockedEntitlement":false,
              "serviceName":"entitlement+billing-service",
              "serviceStateName":"PHASE",
              "phase":"sports-monthly-evergreen",
              "auditLogs":[]
           }
        ],
        "auditLogs":[]
     },
     "auditLogs":[]
  }
]

[{'account_id': '7b26b0ce-a495-4c0c-9dd5-11a556f03e8c',
 'audit_logs': [],
 'bundle_id': '69328cf3-f088-4684-b440-4e2969531930',
 'external_key': '69328cf3-f088-4684-b440-4e2969531930',
 'subscriptions': [{'account_id': '7b26b0ce-a495-4c0c-9dd5-11a556f03e8c',
                    'audit_logs': [],
                    'bill_cycle_day_local': 6,
                    'billing_end_date': None,
                    'billing_period': 'MONTHLY',
                    'billing_start_date': datetime.date(2018, 5, 7),
                    'bundle_id': '69328cf3-f088-4684-b440-4e2969531930',
                    'cancelled_date': None,
                    'charged_through_date': None,
                    'events': [{'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '8a449d77-6894-4903-a048-e625bfec0acd',
                                'event_type': 'START_ENTITLEMENT',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement-service',
                                'service_state_name': 'ENT_STARTED'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 5, 7),
                                'event_id': '996d3548-110c-4870-afa6-a8f0d448b184',
                                'event_type': 'START_BILLING',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-trial',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'billing-service',
                                'service_state_name': 'START_BILLING'},
                               {'audit_logs': [],
                                'billing_period': 'MONTHLY',
                                'effective_date': datetime.date(2018, 6, 6),
                                'event_id': 'e8d24a7d-d463-44dc-ac9d-b41ebbb16a91',
                                'event_type': 'PHASE',
                                'is_blocked_billing': False,
                                'is_blocked_entitlement': False,
                                'phase': 'standard-monthly-evergreen',
                                'plan': 'standard-monthly',
                                'price_list': 'DEFAULT',
                                'product': 'Standard',
                                'service_name': 'entitlement+billing-service',
                                'service_state_name': 'PHASE'}],
                    'external_key': '69328cf3-f088-4684-b440-4e2969531930',
                    'phase_type': 'TRIAL',
                    'plan_name': 'standard-monthly',
                    'price_list': 'DEFAULT',
                    'price_overrides': [],
                    'product_category': 'BASE',
                    'product_name': 'Standard',
                    'source_type': 'NATIVE',
                    'start_date': datetime.date(2018, 5, 7),
                    'state': 'ACTIVE',
                    'subscription_id': '24f54c5b-ee87-407d-a079-22b5d359f2fd'}],
 'timeline': {'account_id': '7b26b0ce-a495-4c0c-9dd5-11a556f03e8c',
              'audit_logs': [],
              'bundle_id': '69328cf3-f088-4684-b440-4e2969531930',
              'events': [{'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '8a449d77-6894-4903-a048-e625bfec0acd',
                          'event_type': 'START_ENTITLEMENT',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement-service',
                          'service_state_name': 'ENT_STARTED'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 5, 7),
                          'event_id': '996d3548-110c-4870-afa6-a8f0d448b184',
                          'event_type': 'START_BILLING',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-trial',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'billing-service',
                          'service_state_name': 'START_BILLING'},
                         {'audit_logs': [],
                          'billing_period': 'MONTHLY',
                          'effective_date': datetime.date(2018, 6, 6),
                          'event_id': 'e8d24a7d-d463-44dc-ac9d-b41ebbb16a91',
                          'event_type': 'PHASE',
                          'is_blocked_billing': False,
                          'is_blocked_entitlement': False,
                          'phase': 'standard-monthly-evergreen',
                          'plan': 'standard-monthly',
                          'price_list': 'DEFAULT',
                          'product': 'Standard',
                          'service_name': 'entitlement+billing-service',
                          'service_state_name': 'PHASE'}],
              'external_key': '69328cf3-f088-4684-b440-4e2969531930'}}]

Query Parameters

Name	Type	Required	Default	Description
searchKey	string	yes	none	String to be matched
offset	long	no	0	Starting index for items listed
limit	long	no	100	maximum number of items listed
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list with all bundles that are matched by the search key.

Invoice

An invoice is a bill provided to a customer for charges that are payable on the customer's account. A single invoice consolidates charges for all subscriptions held by that customer for a specified time period. Invoices may be set to be paid automatically, or may be paid manually by the customer.

An invoice contains a list of InvoiceItems. The system will always invoice at the Account level, and will therefore create as many items on a given invoice as there are things to invoice. Given an active Subscription, one could see multiple items for that subscription on a single invoice including recurring items, usage items, fixed price items, etc. There can also be items for different subscriptions on the same invoice, as well as items that are unrelated to subscriptions such as adjustments and taxes.

An invoice can be generated manually if there are any outstanding charges. In addition, charges can be explicitly added that will also result in an invoice being generated. Invoices can also be automatically generated by the system when there are existing active subscriptions for the Account. In the latter case, the targetDate will determine up to which point to invoice, and the billing mode (IN_ADVANCE or IN_ARREAR) will determine which period to charge for.

An invoice can have one of the following status values: DRAFT, COMMITTED, or VOID.

• An invoice in DRAFT status is open to receive additional items, and is not considered by the rest of the system when computing account balances or related values.

• A COMMITTED invoice is immutable, and its balance is reflected at the Account level. Payments can only happen against COMMITTED invoices.

• A VOID invoice is ignored by the rest of the system. A DRAFT or COMMITTED invoice may be voided, but only if there are no successful payments against that invoice. Thus before voiding an invoice, any successful payments need to be refunded.

Invoice Resource

An Invoice resource represents an invoice associated with a specific account. The attributes contained in this resource are the following:

Name	Type	Generated by	Description
invoiceId	string	system	UUID for the invoice
accountId	string	system	UUID for the account
amount	number	user or system	Sum of all item amounts
currency	string	user or system	Currency associated with the account
status	string	system	Status of the invoice: DRAFT, COMMITTED or VOID
creditAdj	number	system	Invoice credit (amount that we owe to the customer). It is calculated as the sum of CBA_ADJ invoice items
refundAdj	number	system	Refund amount associated with an invoice. It is calculated as the sum of all invoice payment amounts of type REFUND and CHARGED_BACK.
invoiceDate	date	system	Date when this invoice was generated
targetDate	date	user or system	Date up to which the account has been invoiced
invoiceNumber	number	system	Invoice number
balance	number	system	Invoice balance (amount that a customer owes as part of an invoice). At a high level, it is calculated as the sum of all item amounts minus the payment amount. See Invoice Balance for further details.
bundleKeys	list	system	List of bundles invoiced. Deprecated.
credits	list	system	List of credits associated with this invoice. Deprecated.
items	list	system	List of invoice items on this invoice
isParentInvoice	boolean	system	If true, this invoice is the parent in the hierarchical model
parentInvoiceId	string	system	In the hierarchical model, UUID of the parent invoice
parentAccountId	string	system	In the hierarchical model, UUID of the parent account

InvoiceItem Resource

An InvoiceItem resource represents a single item charged on an invoice. The attributes contained in this resource are the following:

Name	Type	Generated by	Description
invoiceItemId	string	system	UUID for the invoice item
invoiceId	string	system	UUID for the invoice
linkedInvoiceItemId	string	system	UUID for the linked item, if any (see below)
accountId	string	system	UUID for the account
childAccountId	string	system	In the hierarchical model, the UUID of the child account
bundleId	string	system	UUID for the bundle
subscriptionId	string	system	UUID for the subscription (present only if invoice item corresponds to a subscription)
planName	string	system	Name of the Plan for this subscription if any
phaseName	string	system	Name of the PlanPhase for this subscription if any
usageName	string	system	Name of the Usage section for this subscription if any
prettyPlanName	string	system	Pretty name of the Plan for this subscription if any
prettyPhaseName	string	system	Pretty name of the PlanPhase for this subscription if any
prettyUsageName	string	system	Pretty name of the Usage section for this subscription if any
itemType	string	system	Item type (see below)
description	string	user or system	Optional description of the item
startDate	date	user or system	Start date of the period invoiced
endDate	date	user or system	End date of the period invoiced
amount	number	user or system	Amount being invoiced
quantity	number	user or system	Rate associated with the Plan
currency	string	user or system	Currency associated with the account
itemDetails	string	user or system	In usage mode, details about what was invoiced.
childItems	list	user or system	In the hierarchical model, the items for the children.

linkedInvoiceItemId: This ID is used to link to another item. For example, an item representing an adjustment would link to the item being adjusted.

itemType: The following invoice item types are currently supported:

• EXTERNAL_CHARGE: Charge independent of any subscription state - typically added using invoice APIs.
• FIXED: Fixed (one-time) charge associated with a subscription.
• RECURRING: Recurring charge associated with a subscription.
• REPAIR_ADJ: Internal adjustment generated by the system, used for billing in advance when the subscription state changed.
• CBA_ADJ: Credit (positive or negative) generated by the system.
• ITEM_ADJ: Invoice item adjustment -- by itself or triggered by a refund.
• USAGE: Usage item
• TAX: Tax item -- this can only be added through an invoice plugin
• PARENT_SUMMARY: In the hierarchical model, represents the summary across all children

Refer to the Subscription Billing document for further details.

InvoiceDryRun Resource

An InvoiceDryRun object represents an invoice preview generated to determine what would be in the invoice scheduled on a certain date, or if certain changes are made. A dry run has no actual effect on the system. The attributes contained in this resource are the following:

Name	Type	Generated by	Description
dryRunType	string	user	Category for this dry run (see notes below)
dryRunAction	string	user	Action on which the dry run should be based, if any (see notes below)
phaseType	string	user	Type of the plan phase (see notes below)
productName	string	user	Name of the product subscribed
productCategory	string	user	Product category (see notes below)
billingPeriod	string	user	Billing period (see notes below)
priceListName	string	user	Name of the applicable price list
subscriptiontId	string	system	UUID for a subscription. If specified, only this subscription is used for the dry run
bundleId	string	system	UUID for a bundle. If specified, only this subscription is used for the dry run
effectiveDate	date	user	The date the change takes effect
billingPolicy	string	user	The billing policy (see notes below)
priceOverrides	list	user	list of prices if this subscription has price overrides

dryRunType: possible values are:

• TARGET_DATE -- Preview the invoice as of the given target date

• UPCOMING_INVOICE -- Preview the next scheduled invoice

• SUBSCRIPTION_ACTION -- Preview the invoice that would be generated if the specified dryRunAction is taken

dryRunAction: possible values are: START_BILLING, CHANGE (of Plan), or STOP_BILLING

phaseType: possible values are: TRIAL, DISCOUNT, FIXEDTERM, or EVERGREEN

productCategory: possible values are BASE, ADD_ON, or STANDALONE

billingPeriod: possible values are DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, SIXTY_DAYS, NINETY_DAYS, MONTHLY, BIMESTRIAL (bimonthly), QUARTERLY, TRIANNUAL, BIANNUAL, ANNUAL, BIENNIAL, or NO_BILLING_PERIOD

billingPolicy: possible values are START_OF_TERM, END_OF_TERM, or IMMEDIATE

Invoice

These endpoints provide basic operations on invoices.

Trigger an invoice run

Create an invoice run for the associated account. This may result in the creation of a new invoice if there is anything to invoice for, or nothing, if the account is up to date. If an invoice is created, all necessary attributes are determined by the system.

Also refer to our subscription manual for more examples

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/invoices?accountId=29fd0a00-f08b-4886-849b-3f4b98c8df27"  

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID accountId = UUID.fromString("5f1e9142-b4de-4409-9366-9920cc1683e9");
LocalDate targetDate = new LocalDate(2012,3,29);

Invoice result = invoiceApi.createFutureInvoice(accountId, 
                                                targetDate, 
                                                requestOptions);

account_id = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0"
target_date = nil

KillBillClient::Model::Invoice.trigger_invoice(account_id, 
                                               target_date, 
                                               user, 
                                               reason, 
                                               comment, 
                                               options)

invoiceApi = killbill.api.InvoiceApi()
target_date = datetime.date(2018, 6, 11)

invoiceApi.create_future_invoice(account_id, 
                                 created_by, 
                                 api_key, 
                                 api_secret, 
                                 target_date=target_date)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5
< Content-Type: application/json
< Content-Length: 0

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@8673fcce
    amount: 249.95
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 139cb81c-6611-4ddf-bb1a-d2c3c47b7a98
    invoiceDate: 2012-05-27
    targetDate: 2012-06-25
    invoiceNumber: 3
    balance: 249.95
    accountId: 5f1e9142-b4de-4409-9366-9920cc1683e9
    bundleKeys: null
    credits: null
    items: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

no content

no content

Query Parameters

Name	Type	Required	Default	Description
accountId	string	yes	none	account id
targetDate	string	no	current date	target date (date up to which the account should be invoiced)

Response

If successful, returns a status code of 201 and an empty body. A location item is also returned in the header, giving the UUID of the generated invoice (if any). If there is nothing to invoice for, returns a 404 status code.

Create a migration invoice

This endpoint is used to insert existing invoices that are being migrated from either a third party system or an in-house billing system into Kill Bill.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/migration/{accountId}

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 '[ { "invoiceItemId": "f38505c9-d673-4f0b-b7d4-9125cac2a567", "invoiceId": "f38505c9-d673-4f0b-b7d4-9125cac2a567", "linkedInvoiceItemId": "f38505c9-d673-4f0b-b7d4-9125cac2a567", "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "itemType": "EXTERNAL_CHARGE", "amount": 10, "rate": 0, "currency": "USD" }]' \
    "http://127.0.0.1:8080/1.0/kb/invoices/migration/2ad52f53-85ae-408a-9879-32a7e59dd03d"  

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID accountId = UUID.fromString("fe1a6f86-9ec5-4ac3-8d39-15f024cc8339");

BigDecimal chargeAmount = BigDecimal.TEN;
InvoiceItem externalCharge = new InvoiceItem();
externalCharge.setStartDate(new LocalDate());
externalCharge.setAccountId(accountId);
externalCharge.setAmount(chargeAmount);
externalCharge.setItemType(InvoiceItemType.EXTERNAL_CHARGE);
externalCharge.setCurrency(Currency.USD);
InvoiceItems inputInvoice = new InvoiceItems();
inputInvoice.add(externalCharge);

LocalDate targetDate = null;

Invoice migrationInvoice = invoiceApi.createMigrationInvoice(accountId, 
                                                             inputInvoice, 
                                                             targetDate,
                                                             requestOptions);

account_id = "be19b229-c076-47aa-aa4d-f53bec505dc7"
invoices = "external_invoice_list"
target_date = "2018-03-15"
KillBillClient::Model::Invoice.create_migration_invoice(account_id, 
                                                        invoices, 
                                                        target_date, 
                                                        user, 
                                                        reason, 
                                                        comment, 
                                                        options)

invoiceApi = killbill.api.InvoiceApi()
body = 'external_invoice_list'
target_date = datetime.date(2018, 6, 11)

invoiceApi.create_migration_invoice(account_id,
                                    [body],
                                    created_by,
                                    api_key,
                                    api_secret,
                                    target_date)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/71742c60-273f-4c91-8b8c-7555a3554b0a/ 
< Content-Type: application/json
< Content-Length: 0

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@7983407c
    amount: 10.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: fb5dadee-f820-4d93-84b1-8cb37a0b8eea
    invoiceDate: 2022-01-31
    targetDate: 2022-01-31
    invoiceNumber: 3139
    balance: 0
    accountId: 85472112-4dcd-4d5e-a345-5716635d7629
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@f50cb1b2
        invoiceItemId: e501ddc2-cf18-4dd5-840e-dbb0527827c3
        invoiceId: fb5dadee-f820-4d93-84b1-8cb37a0b8eea
        linkedInvoiceItemId: null
        accountId: 85472112-4dcd-4d5e-a345-5716635d7629
        childAccountId: null
        bundleId: null
        subscriptionId: null
        productName: null
        planName: null
        phaseName: null
        usageName: null
        prettyProductName: null
        prettyPlanName: null
        prettyPhaseName: null
        prettyUsageName: null
        itemType: FIXED
        description: Fixed price charge
        startDate: 2022-01-31
        endDate: null
        amount: 10.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        catalogEffectiveDate: null
        childItems: null
        auditLogs: []
    }]
    trackingIds: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

no content

no content

Request Body

An invoice resource object with all fields filled in representing the invoice to be migrated. At least the following fields need to be specified: itemType=EXTERNAL_CHARGE, amount.

Query Parameters

Name	Type	Required	Default	Description
targetDate	string	no	current date	target date

Response

If successful, returns a status code of 201 and an empty body. A location item is also returned in the header, giving the UUID of the generated invoice (if any).

Create external charge(s)

Create a charge for a given account. This will result in the creation of a new invoice.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/charges/{accountId}

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", "description": "My charge", "amount": 50, "currency": "USD" }]'    \
    "http://127.0.0.1:8080/1.0/kb/invoices/charges/2ad52f53-85ae-408a-9879-32a7e59dd03d"

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID accountId = UUID.fromString("616789aa-4004-4681-b38c-b95871d534fc");

InvoiceItem externalCharge = new InvoiceItem();
externalCharge.setAccountId(accountId);
externalCharge.setAmount(BigDecimal.TEN);
externalCharge.setDescription("My charge");

InvoiceItems externalCharges = new InvoiceItems();
externalCharges.add(externalCharge);

LocalDate requestedDate = null;
Map<String, String> pluginProperty = null;
Boolean autoCommit = true;

List<InvoiceItem> createdExternalCharges = invoiceApi.createExternalCharges(accountId, 
                                                                            externalCharges, 
                                                                            requestedDate,
                                                                            autoCommit,
                                                                            pluginProperty, 
                                                                            requestOptions);

invoice_item             = KillBillClient::Model::InvoiceItem.new()
invoice_item.account_id  = "83e5e82d-fe72-4873-9b8b-946f4d250b0d"
invoice_item.amount      = '50.0'
invoice_item.currency    = 'USD'
invoice_item.description = 'My charge'

auto_commit = true

invoice_item.create(auto_commit, 
                    user, 
                    reason, 
                    comment, 
                    options)

invoiceApi = killbill.api.InvoiceApi()
body = InvoiceItem(account_id=account_id,
                   amount=50.0,
                   currency='USD',
                   description='My charge')

invoiceApi.create_external_charges(account_id,
                                   [body],
                                   created_by,
                                   api_key,
                                   api_secret,
                                   auto_commit=True)

Example Response:

< HTTP/1.1 201 Created
< Content-Type: application/json
< Content-Length: 0

[
  {
    "invoiceItemId": "3aaadeeb-5ffe-4226-a8b6-57723f1f8c12",
    "invoiceId": "c6fe2246-62e2-450d-b9fc-a27003771535",
    "linkedInvoiceItemId": null,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "childAccountId": null,
    "bundleId": null,
    "subscriptionId": null,
    "productName": null,
    "planName": null,
    "phaseName": null,
    "usageName": null,
    "prettyProductName": null,
    "prettyPlanName": null,
    "prettyPhaseName": null,
    "prettyUsageName": null,
    "itemType": "EXTERNAL_CHARGE",
    "description": "My charge",
    "startDate": "2018-07-20",
    "endDate": null,
    "amount": 50,
    "rate": null,
    "currency": "USD",
    "quantity": null,
    "itemDetails": null,
    "childItems": null,
    "auditLogs": []
  }
]

class InvoiceItem {
    org.killbill.billing.client.model.gen.InvoiceItem@a39beab1
    invoiceItemId: 836d08c4-2bc8-485f-91c1-2dd81b18844e
    invoiceId: 3006fe16-3641-47b6-804e-2719f8f40c87
    linkedInvoiceItemId: 2781cefd-fc73-41d2-9823-f8f0d0b60e2b
    accountId: 616789aa-4004-4681-b38c-b95871d534fc
    childAccountId: null
    bundleId: null
    subscriptionId: null
    productName: null
    planName: null
    phaseName: null
    usageName: null
    prettyProductName: null
    prettyPlanName: null
    prettyPhaseName: null
    prettyUsageName: null
    itemType: EXTERNAL_CHARGE
    description: b1b7442b-cd1b-4bb7-9d30-6b50ea469202
    startDate: 2012-09-25
    endDate: 2012-10-05
    amount: 10.00
    rate: null
    currency: USD
    quantity: null
    itemDetails: Item Details
    childItems: null
    auditLogs: []
}

{
   "invoiceItemId":"4661b7a9-f19f-431e-80ed-547932527fbe",
   "invoiceId":"d27bca74-7e08-4eff-9479-51e8009fe3d0",
   "accountId":"83e5e82d-fe72-4873-9b8b-946f4d250b0d",
   "itemType":"EXTERNAL_CHARGE",
   "description":"My charge",
   "startDate":"2013-08-01",
   "amount":50.0,
   "currency":"USD"
}

no content

Request Body

An invoice item resource object with at least the amount attribute.

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	requested date
autoCommit	boolean	no	false	If true, the resulting invoice should be COMMITTED.

Response

If successful, returns a status code of 201 and an invoice item object.

Create tax items

Normally, tax items are added to an invoice by a plugin, which intercepts the invoice during its creation and adds the required tax items on the fly. However, sometimes you may want to add tax items directly. This API adds a tax item to an account, which will result in the creation of a new invoice.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/taxes/{accountId}

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", "amount": 50, "currency": "USD" }]' \
    "http://127.0.0.1:8080/1.0/kb/invoices/taxes/2ad52f53-85ae-408a-9879-32a7e59dd03d"

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID accountId = UUID.fromString("eb36c64c-b575-4538-b26f-a89c473984da");
UID bundleId = UUID.fromString("28723cec-5510-49be-9e87-3a36d246f25e");

InvoiceItem taxItem = new InvoiceItem();
taxItem.setAccountId(accountId);
taxItem.setAmount(BigDecimal.TEN);
taxItem.setCurrency(Currency.USD);
taxItem.setBundleId(bundleId);
final InvoiceItems input = new InvoiceItems();
input.add(taxItem);

Boolean autoCommit = true;
LocalDate requestedDate = clock.getUTCToday();
Map<String, String> pluginProperty = null;

List<InvoiceItem> createdTaxItems = invoiceApi.createTaxItems(accountId, 
                                                                     input,
                                                                     autoCommit,
                                                                     requestedDate,
                                                                     pluginProperty,
                                                                     requestOptions);

invoice_item             = KillBillClient::Model::InvoiceItem.new()
invoice_item.account_id  = "29ef0d50-90d1-4163-bb46-ef1b82675ae6"
invoice_item.amount      = '50.0'
invoice_item.currency    = 'USD'
invoice_item.description = 'My charge'

auto_commit = true

invoice_item.create_tax_items(auto_commit, 
                              user, 
                              reason, 
                              comment, 
                              options)

invoiceApi = killbill.api.InvoiceApi()
body = InvoiceItem(account_id=account_id,
                   amount=50.0,
                   currency='USD',
                   description='My charge')

invoiceApi.create_tax_items(account_id,
                            [body],
                            created_by,
                            api_key,
                            api_secret,
                            auto_commit=True)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Content-Type: application/json
< Content-Length: 0

[
  {
    "invoiceItemId": "e91e8d48-d8de-4931-9758-6cfff86cb2f4",
    "invoiceId": "434dd357-099d-45f8-9b48-79dcd20c61ce",
    "linkedInvoiceItemId": null,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "childAccountId": null,
    "bundleId": null,
    "subscriptionId": null,
    "productName": null,
    "planName": null,
    "phaseName": null,
    "usageName": null,
    "prettyProductName": null,
    "prettyPlanName": null,
    "prettyPhaseName": null,
    "prettyUsageName": null,
    "itemType": "TAX",
    "description": "Tax",
    "startDate": "2018-07-20",
    "endDate": null,
    "amount": 50,
    "rate": null,
    "currency": "USD",
    "quantity": null,
    "itemDetails": null,
    "childItems": null,
    "auditLogs": []
  }
]

class InvoiceItem {
    org.killbill.billing.client.model.gen.InvoiceItem@bedd818e
    invoiceItemId: 04ebfae8-7898-4c1b-b10e-6fad862e7077
    invoiceId: 000108b4-d0e3-452f-8537-13f6669f8767
    linkedInvoiceItemId: null
    accountId: eb36c64c-b575-4538-b26f-a89c473984da
    childAccountId: null
    bundleId: 28723cec-5510-49be-9e87-3a36d246f25e
    subscriptionId: null
    productName: null
    planName: null
    phaseName: null
    usageName: null
    prettyProductName: null
    prettyPlanName: null
    prettyPhaseName: null
    prettyUsageName: null
    itemType: TAX
    description: Tax
    startDate: 2012-09-25
    endDate: null
    amount: 10.00
    rate: null
    currency: USD
    quantity: null
    itemDetails: null
    childItems: null
    auditLogs: []
}

{
   "invoiceItemId":"20d3bdc8-48c1-48f5-9d9f-5cf0d273dff6",
   "invoiceId":"40655121-ac13-4fe4-af49-02ba668ff4bb",
   "accountId":"29ef0d50-90d1-4163-bb46-ef1b82675ae6",
   "itemType":"TAX",
   "description":"My charge",
   "startDate":"2013-08-01",
   "amount":50.0,
   "currency":"USD",
   "auditLogs":[]
}

no content

Request Body

An invoice item resource object with at least the amount attribute.

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	requested date
autoCommit	boolean	no	false	If true, the resulting invoice should be COMMITTED.

Response

If successful, returns a status code of 201 and an invoice item object.

Retrieve an invoice by id

Retrieves an invoice based on the invoiceId.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}

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/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5"    

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = UUID.fromString("922a83f4-ae08-4732-9dd9-35e13c332393");
Boolean withChildrenItems = false; //  Will include children items

Invoice invoiceWithItems = invoiceApi.getInvoice(invoiceId, 
                                                 withChildrenItems, 
                                                 AuditLevel.NONE, 
                                                 requestOptions);

invoice_id = "31db9f9a-91ff-49f4-b5a1-5e4fce59a197"
with_items = true
audit = 'NONE'

KillBillClient::Model::Invoice.find_by_id(invoice_id, 
                                          with_items, 
                                          audit, 
                                          options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '43da4e9c-03c6-4f15-8943-b9a3af3ecacb'

invoiceApi.get_invoice(invoice_id, api_key, api_secret)

Example Response:

< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "amount": 0,
  "currency": "USD",
  "status": "DRAFT",
  "creditAdj": 50,
  "refundAdj": 0,
  "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5",
  "invoiceDate": "2018-07-20",
  "targetDate": "2018-07-20",
  "invoiceNumber": "310",
  "balance": 0,
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "bundleKeys": null,
  "credits": null,
  "items": [],
  "isParentInvoice": false,
  "parentInvoiceId": null,
  "parentAccountId": null,
  "auditLogs": []
}

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@d6d47bb7
    amount: 10.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 922a83f4-ae08-4732-9dd9-35e13c332393
    invoiceDate: 2012-09-25
    targetDate: 2012-09-25
    invoiceNumber: 3
    balance: 10.00
    accountId: 3db9ebae-3a8e-4cba-ac94-730aeda9a6c3
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@aae429f6
        invoiceItemId: 6288c2a3-d5c6-4f43-bbf4-7e6bf91369d1
        invoiceId: 922a83f4-ae08-4732-9dd9-35e13c332393
        linkedInvoiceItemId: 83716126-1cd4-42bf-907a-22aae31897e7
        accountId: 3db9ebae-3a8e-4cba-ac94-730aeda9a6c3
        childAccountId: null
        bundleId: null
        subscriptionId: null
        productName: null
        planName: null
        phaseName: null
        usageName: null
        prettyProductName: null
        prettyPlanName: null
        prettyPhaseName: null
        prettyUsageName: null
        itemType: EXTERNAL_CHARGE
        description: a8fdf3e2-e071-4f09-b4a4-997c02541366
        startDate: 2012-09-25
        endDate: 2012-10-05
        amount: 10.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: Item Details
        childItems: null
        auditLogs: []
    }]
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

{
   "amount":7.0,
   "currency":"USD",
   "status":"COMMITTED",
   "creditAdj":0.0,
   "refundAdj":0.0,
   "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
   "invoiceDate":"2013-08-01",
   "targetDate":"2013-08-01",
   "invoiceNumber":"1913",
   "balance":0.0,
   "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
   "items":[
      {
         "invoiceItemId":"f641ce8a-a874-4e98-ada5-2bd8fdb74945",
         "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
         "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
         "itemType":"EXTERNAL_CHARGE",
         "description":"My first charge",
         "startDate":"2013-08-01",
         "amount":7.0,
         "currency":"USD",
         "auditLogs":[]
      }
   ],
   "isParentInvoice":false,
   "auditLogs":[]
}

{'account_id': '78bd2ed3-2dc8-4d7c-92da-2a319fd40881',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': '43da4e9c-03c6-4f15-8943-b9a3af3ecacb',
 'invoice_number': '972',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}

Query Parameters

Name	Type	Required	Default	Description
withChildrenItems	boolean	no	false	If true, include children items
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Returns

If successful, returns a status code of 200 and an invoice resource object.

Retrieve an invoice by number

Retrieves an invoice based on the invoiceNumber.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/byNumber/{invoiceNumber

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/invoices/byNumber/310"

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

Integer invoiceNumber = 1;
Boolean withChildrenItems = false; //  Will include children items

Invoice invoiceByNumber = invoiceApi.getInvoiceByNumber(invoiceNumber, 
                                                        withChildrenItems, 
                                                        AuditLevel.FULL, 
                                                        requestOptions);

invoice_number = "1913"
with_items = true
audit = 'NONE'

KillBillClient::Model::Invoice.find_by_number(invoice_number, 
                                              with_items, 
                                              audit, 
                                              options)

invoiceApi = killbill.api.InvoiceApi()
invoice_number = '972'

invoiceApi.get_invoice_by_number(invoice_number, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "amount": 0,
  "currency": "USD",
  "status": "DRAFT",
  "creditAdj": 50,
  "refundAdj": 0,
  "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5",
  "invoiceDate": "2018-07-20",
  "targetDate": "2018-07-20",
  "invoiceNumber": "310",
  "balance": 0,
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "bundleKeys": null,
  "credits": null,
  "items": [],
  "isParentInvoice": false,
  "parentInvoiceId": null,
  "parentAccountId": null,
  "auditLogs": []
}

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@fde9afb7
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 35285f91-07be-4161-8b80-34c8336020df
    invoiceDate: 2012-04-25
    targetDate: 2012-04-25
    invoiceNumber: 1
    balance: 0.00
    accountId: b2fd467c-182e-4ba4-ad93-b12ee43a1dee
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@d77b0a66
        invoiceItemId: da1d65b0-0b27-45bd-b1c9-ef1caea6c08a
        invoiceId: 35285f91-07be-4161-8b80-34c8336020df
        linkedInvoiceItemId: null
        accountId: b2fd467c-182e-4ba4-ad93-b12ee43a1dee
        childAccountId: null
        bundleId: 5f0282c9-28ab-45e1-ba70-53fdf69c2983
        subscriptionId: 4e05f40f-905f-47db-a470-a3c601053741
        productName: Shotgun
        planName: shotgun-monthly
        phaseName: shotgun-monthly-trial
        usageName: null
        prettyProductName: Shotgun
        prettyPlanName: Shotgun Monthly
        prettyPhaseName: shotgun-monthly-trial
        prettyUsageName: null
        itemType: FIXED
        description: shotgun-monthly-trial
        startDate: 2012-04-25
        endDate: null
        amount: 0.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        childItems: null
        auditLogs: [class AuditLog {
            changeType: INSERT
            changeDate: 2012-04-25T00:03:44.000Z
            objectType: INVOICE_ITEM
            objectId: da1d65b0-0b27-45bd-b1c9-ef1caea6c08a
            changedBy: SubscriptionBaseTransition
            reasonCode: null
            comments: null
            userToken: 6cef0bbb-4378-43f7-9d4f-0c70cba8afb0
            history: null
        }]
    }]
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-04-25T00:03:44.000Z
        objectType: INVOICE
        objectId: 35285f91-07be-4161-8b80-34c8336020df
        changedBy: SubscriptionBaseTransition
        reasonCode: null
        comments: null
        userToken: 6cef0bbb-4378-43f7-9d4f-0c70cba8afb0
        history: null
    }]
}

{
   "amount":7.0,
   "currency":"USD",
   "status":"COMMITTED",
   "creditAdj":0.0,
   "refundAdj":0.0,
   "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
   "invoiceDate":"2013-08-01",
   "targetDate":"2013-08-01",
   "invoiceNumber":"1913",
   "balance":0.0,
   "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
   "items":[
      {
         "invoiceItemId":"f641ce8a-a874-4e98-ada5-2bd8fdb74945",
         "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
         "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
         "itemType":"EXTERNAL_CHARGE",
         "description":"My first charge",
         "startDate":"2013-08-01",
         "amount":7.0,
         "currency":"USD",
         "auditLogs":[]
      }
   ],
   "isParentInvoice":false,
   "auditLogs":[]
}

{'account_id': '78bd2ed3-2dc8-4d7c-92da-2a319fd40881',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': '43da4e9c-03c6-4f15-8943-b9a3af3ecacb',
 'invoice_number': '972',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}

Query Parameters

Name	Type	Required	Default	Description
withChildrenItems	boolean	no	false	If true, include children items
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Returns

If successful, returns a status code of 200 and an invoice resource object.

Retrieve an invoice by invoice item id

Retrieves an invoice based on the invoiceItemId for an invoice item.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/byItemId/{itemId}

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/invoices/byItemId/3f0aa8f7-ca75-40cc-8c78-15a15cdbb977"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceItemId = UUID.fromString("111732ad-196d-423f-8ccd-de44109dc944")
Boolean withChildrenItems = false; //  Will include children items

Invoice invoiceByItemId = invoiceApi.getInvoiceByItemId(invoiceItemId, 
                                                        withChildrenItems, 
                                                        AuditLevel.NONE, 
                                                        requestOptions);

invoice_item_id = "f641ce8a-a874-4e98-ada5-2bd8fdb74945"
with_items = true
with_children_items = false
audit = 'NONE'

KillBillClient::Model::Invoice.find_by_invoice_item_id(invoice_item_id, 
                                                       with_items,
                                                       with_children_items, 
                                                       audit, 
                                                       options)

invoiceApi = killbill.api.InvoiceApi()
invoice_item_id = '8fae6721-3ebc-4103-85f5-aa13dde0e4f5'

invoiceApi.get_invoice_by_item_id(invoice_item_id, 
                                  api_key, 
                                  api_secret, 
                                  with_items=True)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "amount": 0,
  "currency": "USD",
  "status": "DRAFT",
  "creditAdj": 50,
  "refundAdj": 0,
  "invoiceId": "18e9b3d9-9083-4725-9e8a-27d3a57c2e88",
  "invoiceDate": "2018-07-20",
  "targetDate": "2018-07-20",
  "invoiceNumber": "311",
  "balance": 0,
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "bundleKeys": null,
  "credits": null,
  "items": [],
  "isParentInvoice": false,
  "parentInvoiceId": null,
  "parentAccountId": null,
  "auditLogs": []
}

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@5c66117a
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 3a51917b-c0f9-4d9d-972e-1c5db7906b1b
    invoiceDate: 2012-04-25
    targetDate: 2012-04-25
    invoiceNumber: 1
    balance: 0.00
    accountId: 3c186380-b31a-4934-b25b-717056219e73
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@74f2032c
        invoiceItemId: 111732ad-196d-423f-8ccd-de44109dc944
        invoiceId: 3a51917b-c0f9-4d9d-972e-1c5db7906b1b
        linkedInvoiceItemId: null
        accountId: 3c186380-b31a-4934-b25b-717056219e73
        childAccountId: null
        bundleId: 66ebdda5-741a-4284-942a-62b2d576b014
        subscriptionId: c8c63a23-f7fd-413a-a8be-4a692c4c7e62
        productName: Shotgun
        planName: shotgun-monthly
        phaseName: shotgun-monthly-trial
        usageName: null
        prettyProductName: Shotgun
        prettyPlanName: Shotgun Monthly
        prettyPhaseName: shotgun-monthly-trial
        prettyUsageName: null
        itemType: FIXED
        description: shotgun-monthly-trial
        startDate: 2012-04-25
        endDate: null
        amount: 0.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        childItems: null
        auditLogs: []
    }]
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

{
   "amount":7.0,
   "currency":"USD",
   "status":"COMMITTED",
   "creditAdj":0.0,
   "refundAdj":0.0,
   "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
   "invoiceDate":"2013-08-01",
   "targetDate":"2013-08-01",
   "invoiceNumber":"1913",
   "balance":0.0,
   "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
   "items":[
      {
         "invoiceItemId":"f641ce8a-a874-4e98-ada5-2bd8fdb74945",
         "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
         "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
         "itemType":"EXTERNAL_CHARGE",
         "description":"My first charge",
         "startDate":"2013-08-01",
         "amount":7.0,
         "currency":"USD",
         "auditLogs":[]
      }
   ],
   "isParentInvoice":false,
   "auditLogs":[]
}

{'account_id': '4d5d7a84-e04e-41ea-80be-871c4eda3610',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 7, 13),
 'invoice_id': 'f14b8e48-aadc-4a68-9d2c-b7e45758e156',
 'invoice_number': '306',
 'is_parent_invoice': False,
 'items': [{'account_id': '4d5d7a84-e04e-41ea-80be-871c4eda3610',
            'amount': 0.0,
            'audit_logs': [],
            'bundle_id': '25b289db-a0e8-4796-a1e3-6c87ee8fef44',
            'child_account_id': None,
            'child_items': None,
            'currency': 'USD',
            'description': 'standard-monthly-trial',
            'end_date': None,
            'invoice_id': 'f14b8e48-aadc-4a68-9d2c-b7e45758e156',
            'invoice_item_id': '8fae6721-3ebc-4103-85f5-aa13dde0e4f5',
            'item_details': None,
            'item_type': 'FIXED',
            'linked_invoice_item_id': None,
            'phase_name': 'standard-monthly-trial',
            'plan_name': 'standard-monthly',
            'pretty_phase_name': 'standard-monthly-trial',
            'pretty_plan_name': 'standard-monthly',
            'pretty_product_name': 'Standard',
            'pretty_usage_name': None,
            'product_name': 'Standard',
            'quantity': None,
            'rate': None,
            'start_date': datetime.date(2018, 7, 13),
            'subscription_id': 'fec6602d-3d11-4039-b09e-86fd488c7082',
            'usage_name': None}],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 7, 13)}                                                                                                                                                                                                                                                                                                        

Query Parameters

Name	Type	Required	Default	Description
withChildrenItems	boolean	no	false	If true, include children items
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and an invoice resource object.

Render an invoice as HTML

This API formats an invoice as an HTML page, that can be displayed or printed for a customer.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/html

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/html" \
    "http://127.0.0.1:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/html"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

String htmlInvoice = invoiceApi.getInvoiceAsHTML(invoiceId, requestOptions);

invoice_id = invoice.invoice_id
KillBillClient::Model::Invoice.as_html(invoice_id, @options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '2c98cfa2-7929-4cc2-9397-1624fb72c6d5'

invoiceApi.get_invoice_as_html(invoice_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: text/html

<html>
    <head>
        <style type="text/css">
            th {align=left; width=225px; border-bottom: solid 2px black;}
        </style>
    </head>
    <body>
        <h1>invoiceTitle</h1>
        <table>
            <tr>
                <td rowspan=3 width=350px>Insert image here</td>
                <td width=100px/>
                <td width=225px/>
                <td width=225px/>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceDate</td>
                <td>Jul 20, 2018</td>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceNumber</td>
                <td>310</td>
            </tr>
            <tr>
                <td>companyName</td>
                <td></td>
                <td align=right>accountOwnerName</td>
                <td>Another Name</td>
            </tr>
            <tr>
                <td>companyAddress</td>
                <td />
                <td />
                <td>john@127.0.0.1:8080</td>
            </tr>
            <tr>
                <td>companyCityProvincePostalCode</td>
                <td />
                <td />
                <td></td>
            </tr>
            <tr>
                <td>companyCountry</td>
                <td />
                <td />
                <td />
            </tr>
            <tr>
                <td><companyUrl</td>
                <td />
                <td />
                <td />
            </tr>
        </table>
        <br />
        <br />
        <br />
        <table>
            <tr>
                <th>invoiceItemBundleName</td>
                <th>invoiceItemDescription</td>
                <th>invoiceItemServicePeriod</td>
                <th>invoiceItemAmount</td>
            </tr>

            <tr>
                <td>Adjustment (account credit)</td>
                <td></td>
                <td>Jul 20, 2018 - Jul 20, 2018</td>
                <td>USD 50.00</td>
            </tr>

            <tr>
                <td>example</td>
                <td></td>
                <td>Jul 20, 2018 - Jul 20, 2018</td>
                <td>USD -50.00</td>
            </tr>

            <tr>
                <td colspan=4 />
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmount</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmountPaid</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceBalance</strong></td>
                <td align=right><strong>0</strong></td>
            </tr>
        </table>
    </body>
</html>

<html>
    <head>
        <style type="text/css">
            th {align=left; width=225px; border-bottom: solid 2px black;}
        </style>
    </head>
    <body>
        <h1>invoiceTitle</h1>
        <table>
            <tr>
                <td rowspan=3 width=350px>Insert image here</td>
                <td width=100px/>
                <td width=225px/>
                <td width=225px/>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceDate</td>
                <td>25 avr. 2012</td>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceNumber</td>
                <td>1</td>
            </tr>
            <tr>
                <td>companyName</td>
                <td></td>
                <td align=right>accountOwnerName</td>
                <td>74c97b13-f1dc-4307-b324-885795bad326</td>
            </tr>
            <tr>
                <td>companyAddress</td>
                <td />
                <td />
                <td>64549@d1fb9</td>
            </tr>
            <tr>
                <td>companyCityProvincePostalCode</td>
                <td />
                <td />
                <td>81 53 26 56</td>
            </tr>
            <tr>
                <td>companyCountry</td>
                <td />
                <td />
                <td />
            </tr>
            <tr>
                <td><companyUrl</td>
                <td />
                <td />
                <td />
            </tr>
        </table>
        <br />
        <br />
        <br />
        <table>
            <tr>
                <th>invoiceItemBundleName</td>
                <th>invoiceItemDescription</td>
                <th>invoiceItemServicePeriod</td>
                <th>invoiceItemAmount</td>
            </tr>

            <tr>
                <td>shotgun-monthly-trial</td>
                <td>Monthly shotgun plan</td>
                <td>25 avr. 2012</td>
                <td>USD 0.00</td>
            </tr>

            <tr>
                <td colspan=4 />
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmount</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmountPaid</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceBalance</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
        </table>
    </body>
</html>

<html>
    <head>
        <style type="text/css">
            th {align=left; width=225px; border-bottom: solid 2px black;}
        </style>
    </head>
    <body>
        <h1>invoiceTitle</h1>
        <table>
            <tr>
                <td rowspan=3 width=350px>Insert image here</td>
                <td width=100px/>
                <td width=225px/>
                <td width=225px/>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceDate</td>
                <td>1 août 2013</td>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceNumber</td>
                <td>2038</td>
            </tr>
            <tr>
                <td>companyName</td>
                <td></td>
                <td align=right>accountOwnerName</td>
                <td>KillBillClient</td>
            </tr>
            <tr>
                <td>companyAddress</td>
                <td />
                <td />
                <td>kill@bill.com</td>
            </tr>
            <tr>
                <td>companyCityProvincePostalCode</td>
                <td />
                <td />
                <td></td>
            </tr>
            <tr>
                <td>companyCountry</td>
                <td />
                <td />
                <td />
            </tr>
            <tr>
                <td><companyUrl</td>
                <td />
                <td />
                <td />
            </tr>
        </table>
        <br />
        <br />
        <br />
        <table>
            <tr>
                <th>invoiceItemBundleName</td>
                <th>invoiceItemDescription</td>
                <th>invoiceItemServicePeriod</td>
                <th>invoiceItemAmount</td>
            </tr>

            <tr>
                <td>My charge</td>
                <td></td>
                <td>1 août 2013</td>
                <td>USD 50.00</td>
            </tr>

            <tr>
                <td colspan=4 />
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmount</strong></td>
                <td align=right><strong>50.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmountPaid</strong></td>
                <td align=right><strong>50.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceBalance</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
        </table>
    </body>
</html>

<html>
    <head>
        <style type="text/css">
            th {align=left; width=225px; border-bottom: solid 2px black;}
        </style>
    </head>
    <body>
        <h1>invoiceTitle</h1>
        <table>
            <tr>
                <td rowspan=3 width=350px>Insert image here</td>
                <td width=100px/>
                <td width=225px/>
                <td width=225px/>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceDate</td>
                <td>May 10, 2018</td>
            </tr>
            <tr>
                <td />
                <td align=right>invoiceNumber</td>
                <td>974</td>
            </tr>
            <tr>
                <td>companyName</td>
                <td></td>
                <td align=right>accountOwnerName</td>
                <td>John</td>
            </tr>
            <tr>
                <td>companyAddress</td>
                <td />
                <td />
                <td></td>
            </tr>
            <tr>
                <td>companyCityProvincePostalCode</td>
                <td />
                <td />
                <td></td>
            </tr>
            <tr>
                <td>companyCountry</td>
                <td />
                <td />
                <td />
            </tr>
            <tr>
                <td><companyUrl</td>
                <td />
                <td />
                <td />
            </tr>
        </table>
        <br />
        <br />
        <br />
        <table>
            <tr>
                <th>invoiceItemBundleName</td>
                <th>invoiceItemDescription</td>
                <th>invoiceItemServicePeriod</td>
                <th>invoiceItemAmount</td>
            </tr>

            <tr>
                <td>standard-monthly-trial</td>
                <td>standard-monthly</td>
                <td>May 10, 2018</td>
                <td>USD 0.00</td>
            </tr>

            <tr>
                <td colspan=4 />
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmount</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceAmountPaid</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
            <tr>
                <td colspan=2 />
                <td align=right><strong>invoiceBalance</strong></td>
                <td align=right><strong>0.00</strong></td>
            </tr>
        </table>
    </body>
</html>

Query Parameters

None.

Response

If successful, returns a status code of 200 and an invoice rendered as HTML.

Change invoice status from DRAFT to COMMITTED

Commit a DRAFT invoice by changing its staus to COMMITTED. The invoice becomes immutable and its balance is now included in account totals.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/commitInvoice

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/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/commitInvoice"  

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = UUID.fromString("ca09d09a-59b2-4ada-8c15-597c9efde46c");

invoiceApi.commitInvoice(invoiceId, requestOptions);

invoice = KillBillClient::Model::Invoice.new
invoice.invoice_id = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5"

invoice.commit(user, 
               reason, 
               comment, 
               options)

invoiceApi = killbill.api.InvoiceApi()

invoiceApi.commit_invoice(invoice_id, 
                          created_by, 
                          api_key, 
                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Void an invoice

Change the status of an invoice to VOID. A void invoice is ignored by the rest of the system. There are some restrictions for this operation:

• We cannot VOID an invoice that was partially or fully paid
• We cannot VOID an invoice if it contains positive credit items (CBA_ADJ >0), unless such credit was not used, i.e there is enough credit left on the account.
• We cannot VOID an invoice if it was repaired, i.e there exists a REPAIR_ADJ item pointing to an item inside that invoice

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/voidInvoice

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/invoices/18e9b3d9-9083-4725-9e8a-27d3a57c2e88/voidInvoice"    

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

invoiceApi.voidInvoice(invoiceId, requestOptions);

TODO

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

invoiceApi.void_invoice(invoice_id, 
                        created_by, 
                        api_key, 
                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Adjust an invoice item

Adjust the amount for an invoice item

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}

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 '{ "invoiceItemId": "903e55d3-8072-47f1-80fc-32857dbdbcc5", "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5", "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "description": "Free adjustment: good customer", "amount": 50, "currency": "USD"}' \
    "http://127.0.0.1:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5"    

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID accountId = UUID.fromString("53805dbc-720a-4eaf-9072-ade723ee860f");
UUID invoiceId = UUID.fromString("4be08988-35a1-4fce-bebc-699af2a95b18");
UUID invoiceItemId = UUID.fromString("5f1e9142-b4de-4409-9366-9920cc1683e9");
BigDecimal adjustedAmount = BigDecimal.TEN;

InvoiceItem adjustmentInvoiceItem = new InvoiceItem();
adjustmentInvoiceItem.setAccountId(accountId);
adjustmentInvoiceItem.setInvoiceId(invoiceItemId);
adjustmentInvoiceItem.setInvoiceItemId(invoiceItemId);
adjustmentInvoiceItem.setAmount(adjustedAmount);
adjustmentInvoiceItem.setCurrency(Currency.USD);

LocalDate requestedDate = null;
Map<String, String> pluginProperty = null;

Invoice result = invoiceApi.adjustInvoiceItem(invoiceId, 
                                              adjustmentInvoiceItem, 
                                              requestedDate,
                                              pluginProperty,
                                              requestOptions);

invoice_item                 = KillBillClient::Model::InvoiceItem.new
invoice_item.account_id      = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0"
invoice_item.invoice_id      = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5"
invoice_item.invoice_item_id = "b311f709-ad51-4f67-8722-18ce04334c31"
invoice_item.amount          = 100.00
invoice_item.currency        = 'USD'
invoice_item.description     = 'Free adjustment: good customer'

invoice_item.update(user, 
                    reason, 
                    comment, 
                    options)

invoiceApi = killbill.api.InvoiceApi()
body = InvoiceItem(account_id='3ee3aa82-1d45-4bbc-b36b-74d628e095d0',
                   invoice_id='2c98cfa2-7929-4cc2-9397-1624fb72c6d5',
                   invoice_item_id='b311f709-ad51-4f67-8722-18ce04334c31',
                   amount=100,
                   currency='USD',
                   description='Free adjustment: good customer')

invoiceApi.adjust_invoice_item(invoice_id,
                               body,
                               created_by,
                               api_key,
                               api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5
< Content-Type: application/json
< Content-Length: 0

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@7ae5a94f
    amount: 224.95
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 4be08988-35a1-4fce-bebc-699af2a95b18
    invoiceDate: 2012-09-25
    targetDate: 2012-09-24
    invoiceNumber: 2
    balance: 224.95
    accountId: 53805dbc-720a-4eaf-9072-ade723ee860f
    bundleKeys: null
    credits: null
    items: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

{
   "amount":400.0,
   "currency":"USD",
   "status":"COMMITTED",
   "creditAdj":0.0,
   "refundAdj":0.0,
   "invoiceId":"2c98cfa2-7929-4cc2-9397-1624fb72c6d5",
   "invoiceDate":"2013-08-31",
   "targetDate":"2013-08-31",
   "invoiceNumber":"1884",
   "balance":0,
   "accountId":"3ee3aa82-1d45-4bbc-b36b-74d628e095d0",
   "items":[],
   "isParentInvoice":false,
   "auditLogs":[]
}

no content

Request Body

An invoice item resource object with at least invoiceItemId, invoiceId, and amount attributes.

Query Parameters

Name	Type	Required	Default	Description
requestedDate	string	no	current date	requested date

Returns

If successful, returns a status code of 201 and an empty body. In addition, a Location header containing the invoice id is returned.

Delete a CBA item

Delete a Credit Balance Adjust (CBA_ADJ) invoice item. There are some limitations and side effects with this api:

1. Deleting a positive CBA_ADJ (credit generation), may lead the system to reclaim portion of the used credit, possibly leaving some invoices with a balance. Example:

Given an invoice, I1, where user added some credit ($12), we would see the following items: {CREDIT_ADJ: -12, CBA_ADJ: +12}. Given another invoice, I2, where the system invoiced for a recurring subscription, and where some of this credit was consumed, we would see the following items: {RECURRING: +10, CBA_ADJ: -10}. Deleting the CBA_ADJ from I1, would lead to the following resulting invoices: I1 {CREDIT_ADJ: 0, CBA_ADJ: 0} and I2 {RECURRING: +10, CBA_ADJ: 0}. The system zeroed-out the credit generation and the part that was used, and as a result I2 would be left with a balance of +10.

1. System generated credit

In an in-advanced scenario where the system first invoiced for a recurring subscription ($20), and then repaired ($-8) for instance as a result of an early cancelation, we would have the following invoices: I1 {RECURRING: +20} and I2 {REPAIR_ADJ: -8, CBA_ADJ: +8}. Attempting to delete the CBA_ADJ on I2 would fail as the generation of credit was system generated, i.e it happened as a result of a subscription change.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/{invoiceItemId}/cba

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/invoices/404a98a8-4dd8-4737-a39f-be871e916a8c/a35fb7b5-aec8-489e-aadf-c86107aa1d92/cba?accountId=8785164f-b5d7-4da1-9495-33f5105e8d80"    

UUID invoiceId = UUID.fromString("c0c2d79d-8b2e-4830-a05b-b9a43b38482c");
UUID invoiceItemId = UUID.fromString("29a8933a-2e5c-409c-97be-7a5964dbf708");
UUID accountId = UUID.fromString("41e61312-cfb1-4300-afc7-64bc5cb29e85");
invoiceApi.deleteCBA(invoiceId, invoiceItemId, accountId, requestOptions);

invoice_item                 = KillBillClient::Model::InvoiceItem.new
invoice_item.account_id      = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0"
invoice_item.invoice_id      = "2c98cfa2-7929-4cc2-9397-1624fb72c6d5"
invoice_item.invoice_item_id = "b311f709-ad51-4f67-8722-18ce04334c31"

invoice_item.delete(user, 
                    reason, 
                    comment, 
                    options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id='2c98cfa2-7929-4cc2-9397-1624fb72c6d5',
invoice_item_id='b311f709-ad51-4f67-8722-18ce04334c31'
account_id = '3ee3aa82-1d45-4bbc-b36b-74d628e095d0',

invoiceApi.delete_cba(invoice_id,
                      invoice_item_id,
                      account_id,
                      created_by,
                      api_key,
                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
accountId	string	yes	none	account id

Response

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

Dry-run

In some situations, it is necessary to preview what a given customer will be invoiced for before making changes, or to verify what the system will generate at a future date. Kill Bill provides a dry-run invoice API to accomplish these goals. This API can be used to answer several distinct questions:

• When is the next upcoming invoice for a given customer, and what will this invoice contain?
• When is the next upcoming invoice associated with a given subscription or bundle, and what will this invoice contain?
• Given a targetDate, what invoice will the system generate?
• Given a change in a subscription, such as a new subscription, change of plan, or cancellation, what invoice will the system generate?

A dry run is based on a dry run resource object.

Generate a dry run invoice

This endpoint creates a dry-run invoice. Based on its parameters you can obtain answers to the different questions listed above.

Note: This endpoint is rather expensive, as it creates a full invoice run for the designated account, but no invoice will be created or persisted in the system.

HTTP Request

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

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 '{ "dryRunType": "TARGET_DATE"}' \
    "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6&targetDate=2022-02-28"   

OR 

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 '{ "dryRunType": "UPCOMING_INVOICE"}' \
    "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=2ad52f53-85ae-408a-9879-32a7e59dd03d"   

OR

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 '{ "dryRunType": "SUBSCRIPTION_ACTION","dryRunAction":"CHANGE","productName":"Standard", "productCategory":"BASE","billingPeriod":"MONTHLY","subscriptionId":"0b9efead-d5e4-40a9-8178-2286dee0fe48","bundleId":" 6ebcc573-c2c4-408a-b5c3-d6ae0dbae233"}' \
    "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6"  

OR

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 '{ "dryRunType": "SUBSCRIPTION_ACTION","dryRunAction":"STOP_BILLING","subscriptionId":"0b9efead-d5e4-40a9-8178-2286dee0fe48","bundleId":"    6ebcc573-c2c4-408a-b5c3-d6ae0dbae233","effectiveDate":"2022-02-10"}' \
    "http://localhost:8080/1.0/kb/invoices/dryRun?accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6"          

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

DryRunType dryRunType = DryRunType.SUBSCRIPTION_ACTION;
SubscriptionEventType dryRunAction = SubscriptionEventType.START_BILLING;
PhaseType phaseType = null;
String productName = "Assault-Rifle";
ProductCategory productCategory = ProductCategory.BASE;
BillingPeriod billingPeriod = BillingPeriod.ANNUAL;
String priceListName = null;
UUID subscriptionId = null;
UUID bundleId = null;
LocalDate effectiveDate = null;
BillingActionPolicy billingPolicy = null;
List<PhasePrice> priceOverrides = null;

InvoiceDryRun dryRunArg = new InvoiceDryRun(dryRunType, 
                                            dryRunAction,
                                            phaseType, 
                                            productName, 
                                            productCategory, 
                                            billingPeriod, 
                                            priceListName, 
                                            subscriptionId, 
                                            bundleId, 
                                            effectiveDate, 
                                            billingPolicy,
                                            priceOverrides);


UUID accountId = UUID.fromString("fe1a6f86-9ec5-4ac3-8d39-15f024cc8339");
LocalDate targetDate = new LocalDate().plusDays(1);

Invoice dryRunInvoice = invoiceApi.generateDryRunInvoice(dryRunArg, 
                                                         accountId, 
                                                         targetDate, 
                                                         requestOptions);

#
# This case is when you create a dry-run invoice with UPCOMING_INVOICE, 
# to see what is the next invoice that the system will generate for this account 
# 
account_id = "5527abbc-d83d-447f-bf3d-ab9542ea631e"
target_date = nil
upcoming_invoice_target_date = true

KillBillClient::Model::Invoice.trigger_invoice_dry_run(account_id, 
                                                       target_date, 
                                                       upcoming_invoice_target_date, 
                                                       options)

#
# This case is when you create a dry-run invoice with UPCOMING_INVOICE, 
# to see what is the next invoice that the system will generate for this account 
# 
invoiceApi = killbill.api.InvoiceApi()
body = InvoiceDryRun(dry_run_type='UPCOMING_INVOICE')
account_id = '00e87495-92dc-4640-8490-e2c794748151'

invoiceApi.generate_dry_run_invoice(body,
                                    account_id,
                                    created_by,
                                    api_key,
                                    api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Content-Type: application/json
{
  "amount": 60,
  "currency": "USD",
  "status": "COMMITTED",
  "creditAdj": 0,
  "refundAdj": 0,
  "invoiceId": "cf4d1d3b-81cf-4054-96d7-bbdada2b9bc2",
  "invoiceDate": "2022-01-31",
  "targetDate": "2022-02-28",
  "invoiceNumber": null,
  "balance": 60,
  "accountId": "60a47168-7d36-4380-8ec7-e48cfe4e65d6",
  "bundleKeys": null,
  "credits": null,
  "items": [
    {
      "invoiceItemId": "8c453b1b-ba2c-4c05-894f-e02eb2ee834e",
      "invoiceId": "cf4d1d3b-81cf-4054-96d7-bbdada2b9bc2",
      "linkedInvoiceItemId": null,
      "accountId": "60a47168-7d36-4380-8ec7-e48cfe4e65d6",
      "childAccountId": null,
      "bundleId": "6ebcc573-c2c4-408a-b5c3-d6ae0dbae233",
      "subscriptionId": "0b9efead-d5e4-40a9-8178-2286dee0fe48",
      "productName": "Standard",
      "planName": "standard-monthly",
      "phaseName": "standard-monthly-evergreen",
      "usageName": null,
      "prettyProductName": null,
      "prettyPlanName": null,
      "prettyPhaseName": null,
      "prettyUsageName": null,
      "itemType": "RECURRING",
      "description": "standard-monthly-evergreen",
      "startDate": "2022-02-28",
      "endDate": "2022-03-31",
      "amount": 30,
      "rate": 30,
      "currency": "USD",
      "quantity": null,
      "itemDetails": null,
      "catalogEffectiveDate": "2019-01-01T00:00:00.000Z",
      "childItems": null,
      "auditLogs": []
    },
    {
      "invoiceItemId": "c1e83a72-ef8e-42d4-93e1-b5f9390294b4",
      "invoiceId": "cf4d1d3b-81cf-4054-96d7-bbdada2b9bc2",
      "linkedInvoiceItemId": null,
      "accountId": "60a47168-7d36-4380-8ec7-e48cfe4e65d6",
      "childAccountId": null,
      "bundleId": "c22936f6-5105-45b6-b418-ebba142a17aa",
      "subscriptionId": "9cce25a5-6ef2-40fe-8718-ca22529fe9d8",
      "productName": "Standard",
      "planName": "standard-monthly",
      "phaseName": "standard-monthly-evergreen",
      "usageName": null,
      "prettyProductName": null,
      "prettyPlanName": null,
      "prettyPhaseName": null,
      "prettyUsageName": null,
      "itemType": "RECURRING",
      "description": "standard-monthly-evergreen",
      "startDate": "2022-02-28",
      "endDate": "2022-03-31",
      "amount": 30,
      "rate": 30,
      "currency": "USD",
      "quantity": null,
      "itemDetails": null,
      "catalogEffectiveDate": "2019-01-01T00:00:00.000Z",
      "childItems": null,
      "auditLogs": []
    }
  ],
  "trackingIds": [],
  "isParentInvoice": false,
  "parentInvoiceId": null,
  "parentAccountId": null,
  "auditLogs": []
}

class Invoice {
    org.killbill.billing.client.model.gen.Invoice@2e7ac6ec
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: ef25cb16-08ef-4945-a875-c6ffa3c1fd77
    invoiceDate: 2012-04-25
    targetDate: 2012-04-25
    invoiceNumber: null
    balance: 0.00
    accountId: fe1a6f86-9ec5-4ac3-8d39-15f024cc8339
    bundleKeys: null
    credits: null
    items: [class InvoiceItem {
        org.killbill.billing.client.model.gen.InvoiceItem@8be409a8
        invoiceItemId: 514a2e5c-b3d4-4d67-8825-f56968b84493
        invoiceId: ef25cb16-08ef-4945-a875-c6ffa3c1fd77
        linkedInvoiceItemId: null
        accountId: fe1a6f86-9ec5-4ac3-8d39-15f024cc8339
        childAccountId: null
        bundleId: ca41fb1a-e8ff-4adc-a481-96510d9726b0
        subscriptionId: 3e8f647c-2e8c-4256-9afd-86dd640486d8
        productName: Assault-Rifle
        planName: assault-rifle-annual
        phaseName: assault-rifle-annual-trial
        usageName: null
        prettyProductName: null
        prettyPlanName: null
        prettyPhaseName: null
        prettyUsageName: null
        itemType: FIXED
        description: assault-rifle-annual-trial
        startDate: 2012-04-25
        endDate: null
        amount: 0.00
        rate: null
        currency: USD
        quantity: null
        itemDetails: null
        childItems: null
        auditLogs: []
    }]
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

{
   "amount":500.0,
   "currency":"USD",
   "status":"COMMITTED",
   "creditAdj":0.0,
   "refundAdj":0.0,
   "invoiceId":"8c62095e-898d-444e-a05b-a498f8bd9d1b",
   "invoiceDate":"2013-08-01",
   "targetDate":"2013-08-31",
   "balance":500.0,
   "accountId":"5527abbc-d83d-447f-bf3d-ab9542ea631e",
   "items":[
      {
         "invoiceItemId":"a45f76a2-7775-4053-bd7c-50a7542e52d3",
         "invoiceId":"8c62095e-898d-444e-a05b-a498f8bd9d1b",
         "accountId":"5527abbc-d83d-447f-bf3d-ab9542ea631e",
         "bundleId":"8e26532b-e5c0-4d4a-b2f0-2eeec8668ada",
         "subscriptionId":"466e26d9-6e44-4afb-9c2f-2b93a4f52329",
         "planName":"sports-monthly",
         "phaseName":"sports-monthly-evergreen",
         "itemType":"RECURRING",
         "description":"sports-monthly-evergreen",
         "startDate":"2013-08-31",
         "endDate":"2013-09-30",
         "amount":500.0,
         "currency":"USD"
      }
   ],
   "isParentInvoice":false
}

{'account_id': '00e87495-92dc-4640-8490-e2c794748151',
 'amount': 100.0,
 'audit_logs': [],
 'balance': 100.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': 'a1c2ab02-d5d8-450d-bb7c-e8f169018570',
 'invoice_number': None,
 'is_parent_invoice': False,
 'items': [{'account_id': '00e87495-92dc-4640-8490-e2c794748151',
            'amount': 100.0,
            'audit_logs': [],
            'bundle_id': '3c02be83-3c2d-4f5a-827e-edfe85266d54',
            'child_account_id': None,
            'child_items': None,
            'currency': 'USD',
            'description': 'standard-monthly-evergreen',
            'end_date': datetime.date(2018, 8, 9),
            'invoice_id': 'a1c2ab02-d5d8-450d-bb7c-e8f169018570',
            'invoice_item_id': 'fe1ec859-dbb9-4851-a030-709a32672bca',
            'item_details': None,
            'item_type': 'RECURRING',
            'linked_invoice_item_id': None,
            'phase_name': 'standard-monthly-evergreen',
            'plan_name': 'standard-monthly',
            'pretty_phase_name': None,
            'pretty_plan_name': None,
            'pretty_usage_name': None,
            'quantity': None,
            'rate': 100.0,
            'start_date': datetime.date(2018, 7, 9),
            'subscription_id': '99e4caa5-d5da-4243-8c91-a38c5cd29632',
            'usage_name': None}],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 7, 9)}

Request Body

A dry run resource object. The dryRunType and sometimes dryRunAction must be specified. Other attributes depend on these:

dryRunType	dryRunAction	Other Required Attributes	Other Optional Attributes	Description
TARGET_DATE	N/A	none	none	Preview the invoice as of the target date specified as a query parameter
UPCOMING_INVOICE	N/A	none	subscriptionId or bundleId (When specified, computes the upcoming invoice for the specified subscription/bundle. Note that if there are other subscriptions invoiced on the same day, these will also be included in the upcoming invoice)	Preview the next scheduled invoice. targetDate query parameter does not need to be specified, it is ignored even if specified
SUBSCRIPTION_ACTION	START_BILLING or CHANGE	productName, productCategory, billingPeriod, subscriptionId, bundleId	effectiveDate, priceListName, billingPolicy	Preview the invoice that would be generated if the START_BILLING or CHANGE action is taken
SUBSCRIPTION_ACTION	STOP_BILLING	subscriptionId, bundleId	effectiveDate	Preview the invoice that would be generated if the STOP_BILLING action is taken

Query Parameters

Name	Type	Required	Default	Description
accountId	string	yes	none	Account id
targetDate	string	No	current date	Target date is the invoicing target date

Note that for SUBSCRIPTION_ACTION, there are 2 dates to take into account:

• The effectiveDate in the body specifies when the action (e.g CREATE) takes place
• The targetDate as a query parameter specifies the date for the billing, i.e how far in the future we want to bill for. A null targetDate default to now.

Response

If successful, returns a status code of 200 and an invoice resource object.

Payments

These endpoints relate to payments on an invoice. More information can be found at Invoice Payments.

Trigger a payment for an invoice

This API causes the system to generate a payment for an invoice.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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 '{ "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d", "purchasedAmount": 50, "targetInvoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5"}' \
    "http://localhost:8080/1.0/kb/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/payments?externalPayment=false" 

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = UUID.fromString("4defec0a-3ecb-4d6f-9b97-c3842734d95f");
UUID accountId = UUID.fromString("14eadca7-dc35-4bbf-bb2b-fabad9bfebcf");

InvoicePayment invoicePayment = new InvoicePayment();
invoicePayment.setPurchasedAmount(BigDecimal.TEN);
invoicePayment.setAccountId(accountId);
invoicePayment.setTargetInvoiceId(invoiceId);

Boolean externalPayment = true; // Will use a external payment method
Map<String, String> pluginProperty = null;
InvoicePayment result = invoiceApi.createInstantPayment(invoiceId, 
                                                        invoicePayment, 
                                                        externalPayment, 
                                                        pluginProperty, 
                                                        requestOptions);

payment                  = KillBillClient::Model::InvoicePayment.new
payment.account_id       = "3ee3aa82-1d45-4bbc-b36b-74d628e095d0"
payment.purchased_amount = '50.0'

external_payment = true

payment.create(external_payment, 
               user, 
               reason, 
               comment, 
               options)

invoiceApi = killbill.api.InvoiceApi()
body = InvoicePayment(account_id=account_id,
                      purchased_amount=50.0,
                      target_invoice_id=invoice_id)

invoiceApi.create_instant_payment(invoice_id,
                                  body,
                                  created_by,
                                  api_key,
                                  api_secret,
                                  external_payment=True)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 No Content
< Content-Type: application/json

class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@abf605f2
    targetInvoiceId: 4defec0a-3ecb-4d6f-9b97-c3842734d95f
    accountId: 14eadca7-dc35-4bbf-bb2b-fabad9bfebcf
    paymentId: 67547a02-2d82-4f39-bff5-ecd1c8a43749
    paymentNumber: 1
    paymentExternalKey: 67547a02-2d82-4f39-bff5-ecd1c8a43749
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 10.00
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: a6655592-994e-4975-888e-c86bda52f2b4
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@2452e8fa
        transactionId: ce51186f-c908-41a3-8ba8-bff57806891f
        transactionExternalKey: ce51186f-c908-41a3-8ba8-bff57806891f
        paymentId: 67547a02-2d82-4f39-bff5-ecd1c8a43749
        paymentExternalKey: 67547a02-2d82-4f39-bff5-ecd1c8a43749
        transactionType: PURCHASE
        amount: 10.00
        currency: USD
        effectiveDate: 2012-09-25T00:00:08.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: null
        gatewayErrorMsg: null
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

no content

no content

Request Body

An invoicePayment resource object, with at least the following attributes: accountId, and purchasedAmount.

Query Parameters

Name	Type	Required	Default	Description
externalPayment	boolean	no	false	If true, the payment method should be defaulted to the (system provided) external payment method.

Response

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

Retrieve payments associated with an invoice

Retrieves a list of invoicePayment objects for payments associated with the invoice

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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/invoices/903e55d3-8072-47f1-80fc-32857dbdbcc5/payments"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = UUID.fromString("ca09d09a-59b2-4ada-8c15-597c9efde46c");
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = false; // Will not reflect payment attempts

InvoicePayments invoicePayments = invoiceApi.getPaymentsForInvoice(invoiceId,
                                                                   withPluginInfo,
                                                                   withAttempts,
                                                                   AuditLevel.NONE,
                                                                   inputOptions);

TODO

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '8291871e-b16e-45e6-a971-577d44727327'

invoiceApi.get_payments_for_invoice(invoice_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "targetInvoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5",
  "accountId": "8b66b9f9-bfb4-463a-86c7-e267128a294a",
  "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
  "paymentNumber": "19",
  "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 500,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "39f3461c-5357-42f7-a8a9-ec79502fdb6b",
  "transactions": [
    {
      "transactionId": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "transactionExternalKey": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
      "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
      "transactionType": "PURCHASE",
      "amount": 500,
      "currency": "USD",
      "effectiveDate": "2018-07-19T20:48:34.000Z",
      "processedAmount": 500,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@c52fce27
    targetInvoiceId: ca09d09a-59b2-4ada-8c15-597c9efde46c
    accountId: e4ba4753-8627-4490-8cda-e225701b8ea9
    paymentId: c65bf687-6bae-4af3-b356-113594a9d794
    paymentNumber: 1
    paymentExternalKey: c65bf687-6bae-4af3-b356-113594a9d794
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 00e485a5-4ee9-47d2-8108-47697c07b17c
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@ab8c2dc0
        transactionId: 92ba850a-615b-4435-bdc1-f1abf507fa26
        transactionExternalKey: 92ba850a-615b-4435-bdc1-f1abf507fa26
        paymentId: c65bf687-6bae-4af3-b356-113594a9d794
        paymentExternalKey: c65bf687-6bae-4af3-b356-113594a9d794
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:06.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: PAYMENT_FAILURE
        gatewayErrorCode: gatewayErrorCode
        gatewayErrorMsg: gatewayError
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: [class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@811fb24d
        accountId: e4ba4753-8627-4490-8cda-e225701b8ea9
        paymentMethodId: 00e485a5-4ee9-47d2-8108-47697c07b17c
        paymentExternalKey: c65bf687-6bae-4af3-b356-113594a9d794
        transactionId: 92ba850a-615b-4435-bdc1-f1abf507fa26
        transactionExternalKey: 92ba850a-615b-4435-bdc1-f1abf507fa26
        transactionType: PURCHASE
        effectiveDate: 2012-09-26T00:00:06.000Z
        stateName: RETRIED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: ca09d09a-59b2-4ada-8c15-597c9efde46c
            isUpdatable: false
        }]
        auditLogs: []
    }, class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@37ee17f0
        accountId: e4ba4753-8627-4490-8cda-e225701b8ea9
        paymentMethodId: 00e485a5-4ee9-47d2-8108-47697c07b17c
        paymentExternalKey: c65bf687-6bae-4af3-b356-113594a9d794
        transactionId: null
        transactionExternalKey: 92ba850a-615b-4435-bdc1-f1abf507fa26
        transactionType: PURCHASE
        effectiveDate: 2012-10-04T00:00:06.000Z
        stateName: SCHEDULED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: ca09d09a-59b2-4ada-8c15-597c9efde46c
            isUpdatable: false
        }]
        auditLogs: []
    }]
    auditLogs: []
}

TODO

{'account_id': '8a758318-25fb-46e1-a385-a8f8354ec903',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
 'payment_id': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
 'payment_method_id': 'eb737a51-d230-46fe-ad95-8ddf0b8effe3',
 'payment_number': '337',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'target_invoice_id': '8291871e-b16e-45e6-a971-577d44727327',
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 9, 14, 27, 9, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
                   'payment_id': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '70a36a47-878e-4fd8-8401-1ab2f4403d41',
                   'transaction_id': '70a36a47-878e-4fd8-8401-1ab2f4403d41',
                   'transaction_type': 'PURCHASE'}]}

Query Parameters

Name	Type	Required	Default	Description
withPluginInfo	boolean	no	false	If true, plugin info is included
withAttempts	boolean	no	false	If true, payment attempts are included
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a List of InvoicePayment resource objects.

Custom Fields

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

Add custom fields to an invoice

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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": "INVOICE", "name": "Test Custom Field", "value": "demo_test_value" }]' \
    "http://127.0.0.1:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

invoiceApi.createInvoiceCustomFields(invoiceId, 
                                     customFields, 
                                     requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'INVOICE'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

invoice.add_custom_field(custom_field, 
                         user,
                         reason,
                         comment,
                         options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
body = CustomField(name='Test Custom Field', value='test_value')

invoiceApi.create_invoice_custom_fields(invoice_id,
                                        [body],
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: INVOICE
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"INVOICE",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

Request Body

A list of Custom Field objects. Each object should specify at least the the name and value attribute. For example:

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

Query Parameters

None.

Response

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

Retrieve invoice custom fields

Retrieve the custom fields associated with an invoice

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/customFields

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/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

List<CustomField> customFields = invoiceApi.getInvoiceCustomFields(invoiceId,
                                                                   AuditLevel.NONE,
                                                                   requestOptions);

audit = 'NONE'

invoice.custom_fields(audit, options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'

invoiceApi.get_invoice_custom_fields(invoice_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "customFieldId": "349de10f-4bb1-4e1a-93f6-11b745200bf5",
    "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "objectType": "INVOICE",
    "name": "Test Custom Field",
    "value": "demo_test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: INVOICE
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"INVOICE",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '5670b594-9317-4aeb-bfef-2c2342ec172a',
 'name': 'Test Custom Field',
 'object_id': '4927c1a2-3959-4f71-98e7-ce3ba19c92ac',
 'object_type': 'INVOICE',
 'value': 'test_value'}]

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), 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 invoice

Modify the custom fields associated with an invoice. 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/invoices/{invoiceId}/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": "349de10f-4bb1-4e1a-93f6-11b745200bf5", "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d", "objectType": "INVOICE", "name": "Test Custom Field", "value": "test_modify_value", "auditLogs": [] }]' \
    "http://127.0.0.1:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = 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);

invoiceApi.modifyInvoiceCustomFields(invoiceId, 
                                     customFields, 
                                     requestOptions);

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

invoice.modify_custom_field(custom_field,                                                                                            
                            user, 
                            reason,
                            comment, 
                            options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac'
custom_field_id = '7fb3dde7-0911-4477-99e3-69d142509bb9'
body = CustomField(custom_field_id=custom_field_id, 
                   name='Test Custom Field', 
                   value='test_value')

invoiceApi.modify_invoice_custom_fields(invoice_id, 
                                        [body], 
                                        created_by, 
                                        api_key, 
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Requst Body

A list of Custom Field objects. Each object should specify at least the the customFieldId and value attribute. For example:

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

A JSON string representing a list of custom fields to substitute for the existing ones.

Query Parameters

None.

Response

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

Remove custom fields from invoice

Remove a specified set of custom fields from the invoice

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/customFields

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/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/customFields?customField=349de10f-4bb1-4e1a-93f6-11b745200bf5"  

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = ImmutableList.<UUID>of(customFieldsId);

invoiceApi.deleteInvoiceCustomFields(invoiceId, 
                                     customFieldsList, 
                                     requestOptions);

custom_field_id = custom_field.id

invoice.remove_custom_field(custom_field_id,                                                                                            
                            user, 
                            reason,
                            comment, 
                            options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '4927c1a2-3959-4f71-98e7-ce3ba19c92ac' 

invoiceApi.delete_invoice_custom_fields(invoice_id, 
                                        created_by, 
                                        api_key, 
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	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

See Account Tags for an introduction.

The only system tag applicable for an Invoice is WRITTEN_OFF (00000000-0000-0000-0000-000000000004), which as it's name indicates, is used to write off an unpaid invoice, bringing its balance to $0.

Add tags to invoice

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

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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-000000000004"]' \
    "http://127.0.0.1:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

UUID invoiceId = UUID.fromString("45d6f4c5-21be-49b1-99c5-7b0c3c985bf0");

UUID writtenOffId = UUID.fromString("00000000-0000-0000-0000-000000000004");

Tags result = invoiceApi.createInvoiceTags(invoiceId, 
                                           ImmutableList.<UUID>of(writtenOffId), 
                                           requestOptions);

tag_name = 'TEST'

invoice.add_tag(tag_name,
               user,
               reason,
               comment,
               options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'
tag = ["00000000-0000-0000-0000-000000000004"]

invoiceApi.create_invoice_tags(invoice_id, 
                               tag, 
                               created_by, 
                               api_key, 
                               api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: INVOICE
    objectId: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
    tagDefinitionId: 00000000-0000-0000-0000-000000000004
    tagDefinitionName: WRITTEN_OFF
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"INVOICE",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000004",
      "tagDefinitionName":"WRITTEN_OFF",
      "auditLogs":[

      ]
   }
]

no content

Request Body

A JSON array containing one or more tag definition ids to be added as 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 invoice.

Retrieve invoice tags

Retrieve all tags attached to this invoice.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = invoiceApi.getInvoiceTags(invoiceId, 
                                           includedDeleted, 
                                           AuditLevel.FULL, 
                                           requestOptions);

included_deleted = false
audit = 'NONE'

invoice.tags(included_deleted,
             audit,
             options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '3e94fccf-0f37-40aa-90a4-122a4f381ebc'

invoiceApi.get_invoice_tags(invoice_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "tagId": "e054c84a-0518-4611-92a8-53e849f0affd",
    "objectType": "INVOICE",
    "objectId": "2cd2f4b5-a1c0-42a7-924f-64c7b791332d",
    "tagDefinitionId": "00000000-0000-0000-0000-000000000002",
    "tagDefinitionName": "AUTO_INVOICING_OFF",
    "auditLogs": []
  }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: INVOICE
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 00000000-0000-0000-0000-000000000001
    tagDefinitionName: AUTO_PAY_OFF
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"INVOICE",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"00000000-0000-0000-0000-000000000006",
      "tagDefinitionName":"TEST",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'object_id': '3e94fccf-0f37-40aa-90a4-122a4f381ebc',
 'object_type': 'INVOICE',
 'tag_definition_id': '00000000-0000-0000-0000-000000000002',
 'tag_definition_name': 'AUTO_INVOICING_OFF',
 'tag_id': 'fc7fab6e-751c-4dd3-b7fa-e93a66e42822'}]

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted tags
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from invoice

Removes a list of tags attached to an invoice.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/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/invoices/2cd2f4b5-a1c0-42a7-924f-64c7b791332d/tags?tagDef=00000000-0000-0000-0000-000000000002"   

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

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

invoiceApi.deleteInvoiceTags(invoiceId, 
                             ImmutableList.<UUID>of(autoPayOffId), 
                             requestOptions);

tag_name = 'TEST'

invoice.remove_tag(tag_name,
                  user,
                  reason,
                  comment,
                  options)

invoiceApi = killbill.api.InvoiceApi()
invoice_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

invoiceApi.delete_invoice_tags(invoice_id, 
                               created_by, 
                               api_key, 
                               api_secret,
                               tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of string	yes	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.

Translation

These endpoints support translation of invoices to a different language when required by the customer. Refer to our Internationalization manual for an introduction.

Translation replaces words and phrases in an invoice or catalog with the equivalent words or phrases in a different language. A tenant may upload translation tables for specific locales (e.g., locale fr_FR for French). When a customer accesses an invoice, that invoice will be generated from the system data, formatted using the appropriate template (see below), and translated according to the locale of the customer's account, if a translation table exists for that locale.

Upload the catalog translation for the tenant

Uploads a catalog translation table that will be saved under a specified locale. The translation table gives a translation for specific names in the current catalog.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/catalogTranslation/{locale}

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: text/plain" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '"sports-monthly = Voiture Sport
silver-monthly = plan d'argent mensuel"' \
    "http://localhost:8080/1.0/kb/invoices/catalogTranslation/fr_FR"

String locale = "en_US";
String body = "gold-monthly=plan";
Boolean deleteIfExists = true;
invoiceApi.uploadCatalogTranslation(locale, body, deleteIfExists,requestOptions);

catalog_translation = 'sports-monthly = Voiture Sport'
locale = "fr_FR"
delete_if_exists = false

KillBillClient::Model::Invoice.upload_catalog_translation(catalog_translation, 
                                                          locale, 
                                                          delete_if_exists, 
                                                          user, 
                                                          reason, 
                                                          comment, 
                                                          options)

invoiceApi = killbill.api.InvoiceApi()
locale = 'fr_FR'
body = "sports-monthly = Voiture Sport"

invoiceApi.upload_catalog_translation(locale,
                                      body,
                                      created_by,
                                      api_key,
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/catalogTranslation/fr_FR/ 
< Content-Type: text/plain
< Content-Length: 0

TODO

"sports-monthly = Voiture Sport"

no content

Request Body

A table of translation items. For example:

gold-monthly = plan Or mensuel

silver-monthly = plan d'argent mensuel

Note that this table does not use a special syntax such as JSON. The equals sign is the only punctuation. There are no brackets or quotation marks.

The names translated would be primarily plan names, product names, and other items that may appear on an invoice.

Query Parameters

Name	Type	Required	Default	Description
deleteIfExists	boolean	no	false	if true, delete any existing translations

Response

If successful, returns a status code of 201 and a Location header which can be used to retrieve the catalog translation.

Retrieve the catalog translation for the tenant

Retrieves the catalog translation table that was previously uploaded for a particular locale, if any.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/catalogTranslation/{locale}

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/plain" \
    "http://localhost:8080/1.0/kb/invoices/catalogTranslation/fr_FR"    

String locale = "en_US";
String translation = invoiceApi.getCatalogTranslation(locale, requestOptions);

locale = "fr_FR"
KillBillClient::Model::Invoice.get_catalog_translation(locale, 
                                                       options)

invoiceApi = killbill.api.InvoiceApi()
locale = 'fr_FR'

invoiceApi.get_catalog_translation(locale, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: text/plain
"sports-monthly = Voiture Sport"

"sports-monthly = Voiture Sport"

"sports-monthly = Voiture Sport"

sports-monthly = Voiture Sport

Query Parameters

None.

Response

If successful, returns a status code of 200 and the translation table. A status code of 404 means no table was found for the specified locale.

Upload the invoice translation for the tenant

Uploads an invoice translation table that will be saved under a specified locale. The translation table gives a translation for specific names in the corresponding invoice template.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoices/translation/{locale}

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/plain" \
    -H "Accept: text/plain" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d "invoiceTitle=FACTURE
invoiceDate=Date:
invoiceNumber=Facture #" \
    "http://localhost:8080/1.0/kb/invoices/translation/fr_FR"

String locale = "en_US";
String body = "gold-monthly=plan";
Boolean deleteIfExists = true;
String translation = invoiceApi.uploadInvoiceTranslation(locale, body, deleteIfExists,requestOptions);

invoice_translation = get_resource_as_string("InvoiceTranslation_fr_FR.properties")
locale = "fr_FR"
delete_if_exists = false
KillBillClient::Model::Invoice.upload_invoice_translation(invoice_translation,
                                                          locale,
                                                          delete_if_exists, 
                                                          options)

invoiceApi = killbill.api.InvoiceApi()
locale = 'fr_FR'
body = "sports-monthly = Voiture Sport"

invoiceApi.upload_invoice_translation(locale,
                                      body,
                                      created_by,
                                      api_key,
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/translation/fr_FR/
< Content-Type: text/plain
< Content-Length: 0

TODO

invoiceTitle=FACTURE
invoiceDate=Date:
invoiceNumber=Facture #
invoiceAmount=XXXMontant à payer
invoiceAmountPaid=XXXMontant payé
invoiceBalance=Nouveau montant

accountOwnerName=Chauffeur

companyName=Killbill, Inc.
companyAddress=P.O. Box 1234
companyCityProvincePostalCode=Springfield
companyCountry=USA
companyUrl=http://killbilling.org

invoiceItemBundleName=Armes
invoiceItemDescription=Description
invoiceItemServicePeriod=Periode de facturation
invoiceItemAmount=Montant

processedPaymentCurrency=(*) Le payment à été payé en
processedPaymentRate=Le taux de conversion est

no content

Request Body

A table of translation items. For example:

invoiceTitle=FACTURE

invoiceDate=Date:

invoiceNumber=Facture #

invoiceAmount=Montant à payer

Note that this table does not use a special syntax such as JSON. The equals sign is the only punctuation. There are no brackets or quotation marks.

Query Parameters

Name	Type	Required	Default	Description
deleteIfExists	boolean	no	false	delete translation if exists

Response

If successful, returns a status code of 201 and a Location header which can be used to retrieve the invoice translation.

Retrieve the invoice translation for the tenant

Retrieves the invoice translation table that was previously uploaded for a particular locale, if any.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/translation/{locale}

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/plain" \
    "http://localhost:8080/1.0/kb/invoices/translation/fr_FR"   

String locale = "en_US";
String translation = invoiceApi.getInvoiceTranslation(locale, requestOptions);

locale = "fr_FR"
KillBillClient::Model::Invoice.get_invoice_translation(locale,
                                                       options)

invoiceApi = killbill.api.InvoiceApi()
locale = 'fr_FR'

invoiceApi.get_invoice_translation(locale, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: text/plain

sports-monthly = Voiture Sport

sports-monthly = Voiture Sport

invoiceTitle=FACTURE
invoiceDate=Date:
invoiceNumber=Facture #
invoiceAmount=XXXMontant à payer
invoiceAmountPaid=XXXMontant payé
invoiceBalance=Nouveau montant

accountOwnerName=Chauffeur

companyName=Killbill, Inc.
companyAddress=P.O. Box 1234
companyCityProvincePostalCode=Springfield
companyCountry=USA
companyUrl=http://killbilling.org

invoiceItemBundleName=Armes
invoiceItemDescription=Description
invoiceItemServicePeriod=Periode de facturation
invoiceItemAmount=Montant

processedPaymentCurrency=(*) Le payment à été payé en
processedPaymentRate=Le taux de conversion est

sports-monthly = Voiture Sport

Query Parameters

None.

Response

If successful, returns a status code of 200 and the translation table. A status code of 404 means no table was found for the specified locale.

Template

A template is a document based on mustache that provides the layout information for invoices. The template will be translated according to the translation table, if any, and the invoice data will be filled in by the Kill Bill system. Refer to our Internationalization manual for an introduction.

Upload the manualPay invoice template for the tenant

Uploads an invoice template based on the manual pay option, for accounts that have the MANUAL_PAY tag. These accounts manually pay their invoices (e.g. ACH). Typically, this template will contain extra information like the company bank account details, PO number, etc.

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/html" \
    -H "Accept: text/html" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '"Some_HTML_String"' \
    "http://localhost:8080/1.0/kb/invoices/manualPayTemplate?deleteIfExists=false"  

String body = "Test HTML String";
Boolean deleteIfExists = true;
String template = invoiceApi.uploadInvoiceMPTemplate(body, deleteIfExists,requestOptions);

invoice_template = "Some_HTML_String"
is_manual_pay = true
delete_if_exists = false
KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, 
                                                       is_manual_pay, 
                                                       delete_if_exists, 
                                                       user, 
                                                       reason, 
                                                       comment, 
                                                       options)

invoiceApi = killbill.api.InvoiceApi()
body = 'Some_HTML_String'

invoiceApi.upload_invoice_mp_template(body,
                                      created_by,
                                      api_key,
                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/manualPayTemplate/%7Blocale:.*%7D/ 
< Content-Type: text/html
< Content-Length: 0

Some HTML String

"
<meta charset=\"UTF-8\">

<html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

no content

Request Body

Contains a mustache manual pay template in HTML format.

Query Parameters

Name	Type	Required	Default	Description
deleteIfExists	boolean	no	false	if true, delete any existing manual pay template

Response

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

Retrieve the manualPay invoice template for the tenant

Retrieves the manual pay invoice template previously uploaded for this tenant, if any.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/manualPayTemplate

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/html" \
    "http://localhost:8080/1.0/kb/invoices/manualPayTemplate/"  

String locale = "fr_FR";
String template = invoiceApi.getInvoiceMPTemplate(locale, requestOptions);

is_manual_pay = true

KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay,
                                                    options)

invoiceApi = killbill.api.InvoiceApi()

invoiceApi.get_invoice_mp_template(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: text/html

"Some_HTML_String"

Some_HTML_String

"
<meta charset=\"UTF-8\">

<html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

"<meta charset=\"UTF-8\">

 <html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

Query Parameters

None.

Response

If successful, returns a status code of 201 and the manual pay template.

Upload the invoice template for the tenant

Uploads an invoice template based on an automatic payment method. This is appropriate for accounts without the MANUAL_PAY tag.

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: text/html" \
    -H "Accept: text/html" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d "Some_HTML_String" \
    "http://localhost:8080/1.0/kb/invoices/template"    

String body = "Test HTML String";
Boolean deleteIfExists = true;
String template = invoiceApi.uploadInvoiceTemplate(body, deleteIfExists,requestOptions);

invoice_template = "Some_HTML_String"
is_manual_pay = false
delete_if_exists = false
KillBillClient::Model::Invoice.upload_invoice_template(invoice_template, 
                                                       is_manual_pay, 
                                                       delete_if_exists, 
                                                       user, 
                                                       reason, 
                                                       comment, 
                                                       options)

invoiceApi = killbill.api.InvoiceApi()
body = 'Some_HTML_String'

invoiceApi.upload_invoice_template(body,
                                   created_by,
                                   api_key,
                                   api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://localhost:8080/1.0/kb/invoices/template
< Content-Type: text/html
< Content-Length: 0

Some HTML String

"
<meta charset=\"UTF-8\">

<html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

no content

Request Body

Contains a mustache automatic pay template in HTML format.

Query Parameters

Name	Type	Required	Default	Description
deleteIfExists	boolean	no	false	if true, delete any existing manual pay template

Response

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

Retrieve the invoice template for the tenant

Retrieves the automatic pay invoice template previously uploaded for this tenant, if any.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/template

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: text/html" \
    "http://localhost:8080/1.0/kb/invoices/template"    

String template = invoiceApi.getInvoiceTemplate(requestOptions);

is_manual_pay = false

KillBillClient::Model::Invoice.get_invoice_template(is_manual_pay,
                                                    options)

invoiceApi = killbill.api.InvoiceApi()

invoiceApi.get_invoice_template(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: text/html

Some_HTML_String

Some_HTML_String

"
<meta charset=\"UTF-8\">

<html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

"<meta charset=\"UTF-8\">

 <html>

   <head>

      <style type=\"text/css\"> th {align=left; width=225px; border-bottom: solid 2px black;} </style>

   </head>

   <body>

      <h1>Tenant template: {{text.invoiceTitle}}</h1>

      <table>

         <tr>

            <td rowspan=3 width=350px>Insert image here</td>

            <td width=100px/>                
            <td width=225px/>                
            <td width=225px/>            
         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceDate}}</td>

            <td>{{invoice.formattedInvoiceDate}}</td>

         </tr>

         <tr>

            <td />                
            <td align=right>{{text.invoiceNumber}}</td>

            <td>{{invoice.invoiceNumber}}</td>

         </tr>

         <tr>

            <td>{{text.companyName}}</td>

            <td></td>

            <td align=right>{{text.accountOwnerName}}</td>

            <td>{{account.name}}</td>

         </tr>

         <tr>

            <td>{{text.companyAddress}}</td>

            <td />                
            <td />                
            <td>{{account.email}}</td>

         </tr>

         <tr>

            <td>{{text.companyCityProvincePostalCode}}</td>

            <td />                
            <td />                
            <td>{{account.phone}}</td>

         </tr>

         <tr>

            <td>{{text.companyCountry}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

         <tr>

            <td><{{text.companyUrl}}</td>

            <td />                
            <td />                
            <td />            
         </tr>

      </table>
              <br />        <br />        <br />        
      <table>

         <tr>

            <th>{{text.invoiceItemBundleName}}</td>                
            <th>{{text.invoiceItemDescription}}</td>                
            <th>{{text.invoiceItemServicePeriod}}</td>                
            <th>{{text.invoiceItemAmount}}</td>            
         </tr>
                     {{#invoice.invoiceItems}}            
         <tr>

            <td>{{description}}</td>

            <td>{{planName}}</td>

            <td>{{formattedStartDate}}{{#formattedEndDate}} - {{formattedEndDate}}{{/formattedEndDate}}</td>

            <td>{{invoice.currency}} {{amount}}</td>

         </tr>
                     {{/invoice.invoiceItems}}            
         <tr>

            <td colspan=4 />            
         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmount}}</strong></td>

            <td align=right><strong>{{invoice.chargedAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceAmountPaid}}</strong></td>

            <td align=right><strong>{{invoice.paidAmount}}</strong></td>

         </tr>

         <tr>

            <td colspan=2 />                
            <td align=right><strong>{{text.invoiceBalance}}</strong></td>

            <td align=right><strong>{{invoice.balance}}</strong></td>

         </tr>

      </table>

   </body>

</html>
"

Query Parameters

None.

Response

If successful, returns a status code of 201 and the automatic pay template.

Example

The translation and templating process may seem a little complex. Here is a simple example for the use of a template with translation.

1. To begin, a tenant should upload suitable manual pay and autopay templates reflecting her desired layout for the invoice. If this is not done a default template will be used.

2. Suppose the tenant does business with German customers. She then should upload translation tables, perhaps provided by customers, designated for the German locale (de_DE). Tables are needed for both invoice items and catalog items. The invoice items to be translated are the names of the fields on the template, such as invoiceTitle, invoiceAmount, etc. The catalog items to be translated are the names for actual items such as product name and plan name. There can be translation tables for any number of distinct locales.

Catalog translation example (German):

gold plan = Goldplan sports car = Sportwagen

Invoice transaltion example (German):

invoiceTitle = Rechnung invoiceNumber = Rechnungsnumber invoiceBalance = Rechnungssaldo

1. Each account has a designated locale. When an invoice is retrieved for an account, the appropriate translation tables, if any, are used to translate the invoice.

You can refer to the (Invoice Templates Tutorial)[https://docs.killbill.io/latest/invoice_templates.html] to know more about the how this works.

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 invoice audit logs with history by invoice id

Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoices/{invoiceId}/auditLogsWithHistory

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/invoices/d456a9b3-7e48-4f56-b387-1d65a492e75e/auditLogsWithHistory"

UUID invoiceId = UUID.fromString("8f6f3405-249f-4b66-a0c2-ee84e884e81d");
AuditLogs logs = invoiceApi.getInvoiceAuditLogsWithHistory(invoiceId, requestOptions);

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "INVOICE",
    "objectId": "d456a9b3-7e48-4f56-b387-1d65a492e75e",
    "changedBy": "SubscriptionBaseTransition",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": null,
      "recordId": 2121,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "accountId": "7b3e14b1-6e76-46d3-bbfd-5a16e5b5eca2",
      "invoiceNumber": null,
      "invoiceDate": "2019-02-22",
      "targetDate": "2019-02-22",
      "currency": "USD",
      "migrated": false,
      "status": "COMMITTED",
      "invoiceItems": [],
      "invoicePayments": [],
      "processedCurrency": "USD",
      "parentInvoice": null,
      "isWrittenOff": false,
      "writtenOff": false,
      "tableName": "INVOICES",
      "historyTableName": "INVOICE_HISTORY"
    }
  }
]

[class AuditLog {
    changeType: INSERT
    changeDate: 2022-01-31T00:10:47.000Z
    objectType: INVOICE
    objectId: 8f6f3405-249f-4b66-a0c2-ee84e884e81d
    changedBy: SubscriptionBaseTransition
    reasonCode: null
    comments: null
    userToken: a6bb5711-b9b3-4161-a7c1-69f5c3d574c1
    history: {id=null, createdDate=2022-01-31T00:10:47.000Z, updatedDate=null, recordId=3149, accountRecordId=562, tenantRecordId=1, accountId=60a47168-7d36-4380-8ec7-e48cfe4e65d6, invoiceNumber=null, invoiceDate=2022-01-31, targetDate=2022-01-31, currency=USD, migrated=false, status=COMMITTED, invoiceItems=[], invoicePayments=[], trackingIds=[], processedCurrency=USD, parentInvoice=null, isWrittenOff=false, isRepaired=false, writtenOff=false, repaired=false, tableName=INVOICES, historyTableName=INVOICE_HISTORY}
}]

Query Parameters

None.

Response

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

Retrieve invoice item audit logs with history by invoice item id

Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice item. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoiceItems/{invoiceItemId}/auditLogsWithHistory

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/invoiceItems/b45ef2ac-e4b7-4e79-89d8-1c2e95838300/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "INVOICE_ITEM",
    "objectId": "b45ef2ac-e4b7-4e79-89d8-1c2e95838300",
    "changedBy": "SubscriptionBaseTransition",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": null,
      "recordId": 2698,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "type": "RECURRING",
      "invoiceId": "d456a9b3-7e48-4f56-b387-1d65a492e75e",
      "accountId": "7b3e14b1-6e76-46d3-bbfd-5a16e5b5eca2",
      "childAccountId": null,
      "bundleId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "subscriptionId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
      "description": "foo-monthly-evergreen",
      "productName": "Foo",
      "planName": "foo-monthly",
      "phaseName": "foo-monthly-evergreen",
      "usageName": null,
      "startDate": "2019-02-22",
      "endDate": "2019-03-22",
      "amount": 10,
      "rate": 10,
      "currency": "USD",
      "linkedItemId": null,
      "quantity": null,
      "itemDetails": null,
      "tableName": "INVOICE_ITEMS",
      "historyTableName": "INVOICE_ITEM_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

Retrieve invoice payment audit logs with history by invoice payment id

Retrieve a list of audit log records showing events that occurred involving changes to a specified invoice payment. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{invoicePaymentId}/auditLogsWithHistory

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/invoicePayments/5eedf918-b418-4d14-8dba-51c977a3f700/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T23:23:21.000Z",
    "objectType": "INVOICE_PAYMENT",
    "objectId": "5eedf918-b418-4d14-8dba-51c977a3f700",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "39b3f8a2-d782-41cd-adcd-460b5f560192",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T23:23:21.000Z",
      "updatedDate": null,
      "recordId": 219,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "type": "ATTEMPT",
      "invoiceId": "d456a9b3-7e48-4f56-b387-1d65a492e75e",
      "paymentId": null,
      "paymentDate": "2019-02-22T23:23:21.000Z",
      "amount": 10,
      "currency": "USD",
      "processedCurrency": "USD",
      "paymentCookieId": "4d83dd1b-b053-4a4d-99de-9a9e6e0405af",
      "linkedInvoicePaymentId": null,
      "success": false,
      "tableName": "INVOICE_PAYMENTS",
      "historyTableName": "INVOICE_PAYMENT_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2019-02-22T23:23:21.000Z",
    "objectType": "INVOICE_PAYMENT",
    "objectId": "5eedf918-b418-4d14-8dba-51c977a3f700",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "39b3f8a2-d782-41cd-adcd-460b5f560192",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T23:23:21.000Z",
      "updatedDate": null,
      "recordId": 219,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "type": "ATTEMPT",
      "invoiceId": "d456a9b3-7e48-4f56-b387-1d65a492e75e",
      "paymentId": "3ac3de91-0d94-463d-8286-8060846f229d",
      "paymentDate": "2019-02-22T23:23:21.000Z",
      "amount": 10,
      "currency": "USD",
      "processedCurrency": "USD",
      "paymentCookieId": "4d83dd1b-b053-4a4d-99de-9a9e6e0405af",
      "linkedInvoicePaymentId": null,
      "success": true,
      "tableName": "INVOICE_PAYMENTS",
      "historyTableName": "INVOICE_PAYMENT_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

List and Search

These endpoints allow you to list all invoices or to search for a specific invoice.

List invoices

Retrieve a list of all invoice records for this tenant.

HTTP Request

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

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

Long offset = 0L;
Long limit = 1L;
Invoices result = invoiceApi.getInvoices(offset, 
                                         limit, 
                                         AuditLevel.NONE, 
                                         requestOptions);

offset = 0
limit = 100

invoice.find_in_batches(offset,
                        limit,
                        options)

invoiceApi = killbill.api.InvoiceApi()

invoiceApi.get_invoices(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "404a98a8-4dd8-4737-a39f-be871e916a8c",
    "invoiceDate": "2018-07-19",
    "targetDate": "2018-07-19",
    "invoiceNumber": "309",
    "balance": 0,
    "accountId": "8785164f-b5d7-4da1-9495-33f5105e8d80",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "310",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "VOID",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "18e9b3d9-9083-4725-9e8a-27d3a57c2e88",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "311",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "DRAFT",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "c6fe2246-62e2-450d-b9fc-a27003771535",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "312",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "DRAFT",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "d6c7b6b9-f048-4266-bde6-4c381e69f432",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "313",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "71742c60-273f-4c91-8b8c-7555a3554b0a",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "314",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  },
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "e8032d7d-4354-46f7-82fa-8e635cc61fc5",
    "invoiceDate": "2018-07-20",
    "targetDate": "2018-07-20",
    "invoiceNumber": "315",
    "balance": 0,
    "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  }
]

//First element of the list
class Invoice {
    org.killbill.billing.client.model.gen.Invoice@30849f9
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 1a49101b-305e-4b4d-8403-7377596407b6
    invoiceDate: 2012-08-25
    targetDate: 2012-08-25
    invoiceNumber: 1
    balance: 0.00
    accountId: 715c9695-4730-4fd7-80db-d5e38dfc9aa0
    bundleKeys: null
    credits: null
    items: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

[
    {
       "amount":7.0,
       "currency":"USD",
       "status":"COMMITTED",
       "creditAdj":0.0,
       "refundAdj":0.0,
       "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
       "invoiceDate":"2013-08-01",
       "targetDate":"2013-08-01",
       "invoiceNumber":"1913",
       "balance":0.0,
       "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
       "items":[
          {
             "invoiceItemId":"f641ce8a-a874-4e98-ada5-2bd8fdb74945",
             "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
             "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
             "itemType":"EXTERNAL_CHARGE",
             "description":"My first charge",
             "startDate":"2013-08-01",
             "amount":7.0,
             "currency":"USD",
             "auditLogs":[]
          }
       ],
       "isParentInvoice":false,
       "auditLogs":[]
    }
]

[{'account_id': '40d6c91b-13f4-4689-8acc-b3455ab956ac',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': '14f2bbf3-bd2d-4e32-86eb-b9d32ce4be74',
 'invoice_number': '1015',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}, {'account_id': '7f6894df-d1d6-499b-8cd0-a09da4d3beaf',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': 'cd98fb3b-25a4-4e1c-8426-0c1080531ad9',
 'invoice_number': '1016',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}]

Query Parameters

Name	Type	Required	Default	Description
offset	long	no	0	Starting index for items listed
limit	long	no	100	Maximum number of items to be listed
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Search invoices

Search for an account by a specified search string. If the search string is a number, it is compared to the invoiceNumber attribute. An exact match is required. Otherwise, it is compared to the following attributes: invoiceId, accountId, or currency. The operation returns all account records in which the search string matches all or part of any one of these attributes.

HTTP Request

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

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/invoices/search/404a98a8-4dd8-4737-a39f-be871e916a8c" 

import org.killbill.billing.client.api.gen.InvoiceApi;
protected InvoiceApi invoiceApi;

String searchKey = "1a49101b-305e-4b4d-8403-7377596407b6";

Long offset = 0L;
Long limit = 1L;

invoiceApi.searchInvoices(searchKey, 
                          offset,
                          limit, 
                          AuditLevel.NONE, 
                          requestOptions);

search_key = 'COMMITTED'
offset = 0
limit = 100

invoice.find_in_batches_by_search_key(search_key,
                                      offset,
                                      limit,
                                      options)

invoiceApi = killbill.api.InvoiceApi()
search_key = 'USD'

invoiceApi.search_invoices(search_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "amount": 0,
    "currency": "USD",
    "status": "COMMITTED",
    "creditAdj": 0,
    "refundAdj": 0,
    "invoiceId": "404a98a8-4dd8-4737-a39f-be871e916a8c",
    "invoiceDate": "2018-07-19",
    "targetDate": "2018-07-19",
    "invoiceNumber": "309",
    "balance": 0,
    "accountId": "8785164f-b5d7-4da1-9495-33f5105e8d80",
    "bundleKeys": null,
    "credits": null,
    "items": [],
    "isParentInvoice": false,
    "parentInvoiceId": null,
    "parentAccountId": null,
    "auditLogs": []
  }
]

//First element of the list
class Invoice {
    org.killbill.billing.client.model.gen.Invoice@30849f9
    amount: 0.00
    currency: USD
    status: COMMITTED
    creditAdj: 0.00
    refundAdj: 0.00
    invoiceId: 1a49101b-305e-4b4d-8403-7377596407b6
    invoiceDate: 2012-08-25
    targetDate: 2012-08-25
    invoiceNumber: 1
    balance: 0.00
    accountId: 715c9695-4730-4fd7-80db-d5e38dfc9aa0
    bundleKeys: null
    credits: null
    items: []
    isParentInvoice: false
    parentInvoiceId: null
    parentAccountId: null
    auditLogs: []
}

[
    {
       "amount":7.0,
       "currency":"USD",
       "status":"COMMITTED",
       "creditAdj":0.0,
       "refundAdj":0.0,
       "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
       "invoiceDate":"2013-08-01",
       "targetDate":"2013-08-01",
       "invoiceNumber":"1913",
       "balance":0.0,
       "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
       "items":[
          {
             "invoiceItemId":"f641ce8a-a874-4e98-ada5-2bd8fdb74945",
             "invoiceId":"31db9f9a-91ff-49f4-b5a1-5e4fce59a197",
             "accountId":"be19b229-c076-47aa-aa4d-f53bec505dc7",
             "itemType":"EXTERNAL_CHARGE",
             "description":"My first charge",
             "startDate":"2013-08-01",
             "amount":7.0,
             "currency":"USD",
             "auditLogs":[]
          }
       ],
       "isParentInvoice":false,
       "auditLogs":[]
    }
]

[{'account_id': '554f89d7-c9bd-4e48-a28d-5d2d88f0ea19',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': '5ffe67ba-322a-407c-8051-0a5839774a1c',
 'invoice_number': '1017',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}, {'account_id': '58e8ffe1-d01e-4716-bf46-c76b881b6574',
 'amount': 0.0,
 'audit_logs': [],
 'balance': 0.0,
 'bundle_keys': None,
 'credit_adj': 0.0,
 'credits': None,
 'currency': 'USD',
 'invoice_date': datetime.date(2018, 5, 10),
 'invoice_id': '4a836b76-447c-4d5c-9dc7-96f1c9b0cf9c',
 'invoice_number': '1018',
 'is_parent_invoice': False,
 'items': [],
 'parent_account_id': None,
 'parent_invoice_id': None,
 'refund_adj': 0.0,
 'status': 'COMMITTED',
 'target_date': datetime.date(2018, 5, 10)}]

Query Parameters

Name	Type	Required	Default	Description
searchKey	string	yes	none	What you want to find
offset	long	none	0	Starting index for items listed
limit	long	none	100	Maximum number of items to return on this page
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a list of all invoices matched with the search key entered.

Credit

Credit Resource

The Credit resource represents the credits created on behalf of the customer Account. Credits are tracked inside invoices, as a specical kind of invoice item. The credits are visible at the level of the Account, i.e account credit, and those will automatically be consumed by the system on subsequent invoices to bring the balance to zero -- or reduce the balance if there is not enough credit to pay the full amount.

See section Invoice Resource for the description of the InvoiceItem attributes.

Credit

Basic endpoints to create and retrieve credit invoice items

Create credits

Create one or more credits for a specified account. These credits will appear as invoiceItems. They may be added to an existing DRAFT invoice, or they may result in the creation of a new invoice.

HTTP Request

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

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 '[{"amount": 50.0, "currency": "USD", "accountId": "1f979085-1765-471b-878a-5f640db4d831", "description": "example"}]' \
    "http://localhost:8080/1.0/kb/credits?autoCommit=true"

import org.killbill.billing.client.api.gen.CreditApi;
protected CreditApi creditApi;

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

Credit credit = new InvoiceItem();
credit.setAccountId(accountId);
credit.setAmount(BigDecimal.ONE);
credit.setDescription("description");

Boolean autoCommit = true;
Map<String, String> pluginProperty = null;

final InvoiceItems credits = new InvoiceItems();
credits.add(credit);
InvoiceItems createdCredits = creditApi.createCredits(credits, false, NULL_PLUGIN_PROPERTIES, requestOptions);

credit_item                 = KillBillClient::Model::Credit.new()
credit_item.account_id      = 'da3769a8-58c4-4dc0-b4e8-7b534e349624'
credit_item.amount          = 50.0
credit_item.currency        = 'USD'
credit_item.description     = 'description'

auto_commit = true

credit_item.create(auto_commit, 
                   user,
                   reason,
                   comment,
                   options)

creditApi = killbill.api.CreditApi()
body = Credit(account_id=account_id, 
              amount=50.0, 
              currency='USD', 
              description='example')

creditApi.create_credits([body], created_by, api_key, api_secret)

Example Response:

    < HTTP/1.1 200 OK
[
  {
    "invoiceItemId": "2a7746a3-abad-42d9-9f54-fe50c0b18802",
    "invoiceId": "e3caf986-8909-4677-afd4-ba03deeae8f0",
    "linkedInvoiceItemId": null,
    "accountId": "1f979085-1765-471b-878a-5f640db4d831",
    "childAccountId": null,
    "bundleId": null,
    "subscriptionId": null,
    "productName": null,
    "planName": null,
    "phaseName": null,
    "usageName": null,
    "prettyProductName": null,
    "prettyPlanName": null,
    "prettyPhaseName": null,
    "prettyUsageName": null,
    "itemType": "CREDIT_ADJ",
    "description": "example",
    "startDate": "2020-01-17",
    "endDate": "2020-01-17",
    "amount": 50,
    "rate": null,
    "currency": "USD",
    "quantity": null,
    "itemDetails": null,
    "catalogEffectiveDate": null,
    "childItems": null,
    "auditLogs": []
  }
]

class Credit {
    org.killbill.billing.client.model.gen.Credit@a32400a5
    creditId: d2edf4c0-9929-4e2f-b3a9-feb9bd9d60ba
    creditAmount: 1.00
    currency: USD
    invoiceId: 41c87837-ec1d-4095-8d20-a56e6237cb0c
    invoiceNumber: 3
    effectiveDate: 2012-09-26
    accountId: 7cf30d01-84f1-4d9d-94c2-3a3277374960
    description: description
    itemDetails: itemDetails
    auditLogs: []
}

{
   "creditId":"fd5669a8-68c1-8dl0-m4e8-8y535e349324"
   "amount":50.0,
   "currency":"USD",
   "invoiceId":"c57e1a2b-1a6b-4053-be2c-cc5fad2b5cbf",
   "invoiceNumber":"1285",
   "effectiveDate":"2013-08-01",
   "accountId":"da3769a8-58c4-4dc0-b4e8-7b534e349624",
   "description":"description"
}

no content

Request Body

A list of one or more invoiceItem objects. Each object requires at least the following attributes: accountId and amount. If an invoiceId is given, the item will be added to the specified invoice. This invoice must be in DRAFT status or an error will occur.

Query Parameters

Name	Type	Required	Default	Description
autoCommit	boolean	no	false	if true, the resulting invoice will be COMMITTED.

Returns

If successful, returns a status code of 200 and a list of invoiceItem resource objects representing the credit(s).

Retrieve a credit by id

Retrieve an invoiceItem representing a credit given the invoiceItemId.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/credits/{invoiceItemId}

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/credits/c8bfa9d1-76e5-4a42-92d0-b106c0902c16" 

import org.killbill.billing.client.api.gen.CreditApi;
protected CreditApi creditApi;

UUID creditId = UUID.fromString("d2edf4c0-9929-4e2f-b3a9-feb9bd9d60ba");

Credit result = creditApi.getCredit(creditId, requestOptions)

credit_id = 'fd5669a8-68c1-8dl0-m4e8-8y535e349324'

KillBillClient::Model::Credit.find_by_id(credit_id , options)

creditApi = killbill.api.CreditApi()

creditApi.get_credit(credit_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

{
  "invoiceItemId": "c8bfa9d1-76e5-4a42-92d0-b106c0902c16",
  "amount": 50,
  "currency": "USD",
  "invoiceId": "903e55d3-8072-47f1-80fc-32857dbdbcc5",
  "invoiceNumber": "310",
  "effectiveDate": "2018-07-20",
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "description": "example",
  "itemDetails": null,
  "auditLogs": []
}

class Credit {
    org.killbill.billing.client.model.gen.InvoiceItem@a32400a5
    invoiceItemId: d2edf4c0-9929-4e2f-b3a9-feb9bd9d60ba
    amount: 1.00
    currency: USD
    invoiceId: 41c87837-ec1d-4095-8d20-a56e6237cb0c
    invoiceNumber: 3
    effectiveDate: 2012-09-26
    accountId: 7cf30d01-84f1-4d9d-94c2-3a3277374960
    description: description
    itemDetails: itemDetails
    auditLogs: []
}

{
   "invoiceItemId":"fd5669a8-68c1-8dl0-m4e8-8y535e349324"
   "amount":50.0,
   "currency":"USD",
   "invoiceId":"c57e1a2b-1a6b-4053-be2c-cc5fad2b5cbf",
   "invoiceNumber":"1285",
   "effectiveDate":"2013-08-01",
   "accountId":"da3769a8-58c4-4dc0-b4e8-7b534e349624",
   "description":"description"
}

{'invoice_item_id' : 'fd5669a8-68c1-8dl0-m4e8-8y535e349328'
 'account_id': 'da3769a8-58c4-4dc0-b4e8-7b534e349624',
 'amount': 50.0,
 'currency': 'USD',
 'description': 'example',
 'effective_date': datetime.datetime(2018, 5, 3, 15, 53, 44, tzinfo=tzutc()),,
 'invoice_id': 'c57e1a2b-1a6b-4053-be2c-cc5fad2b5cbf',
 'invoice_number': '1285'
}

Query Parameters

None.

Returns

If successful, returns a status code of 200 and an invoiceItem resource object with itemType CREDIT_ADJ representing a credit.

Payment

A Payment in Kill Bill is an amount paid or payable on a specific account due to an invoice or independent of any invoice.

A Payment may be associated with a series of PaymentTransactions, such as authorization, payment attempt, chargeback, etc. each of which may succeed or fail.

A Payment Transaction takes place using a PaymentMethod such as a credit card. The transaction is processed by a plugin, which provides access to the appropriate payment gateway. The payment gateway processes the transaction, using the Payment Method provided in the request.

A Payment Attempt is an attempt to perform a Payment Transaction. A Payment Attempt may succeed or fail, and a Payment Transaction may have more than one Payment Attempt. In some cases a Payment Transaction may be in a PENDING state waiting for completion of its processing by the plugin.

Please refer to the payment manual for more details.

Payment Resource

A Payment is represented by a Payment resource object. The attributes for the Payment resource are as follows:

Name	Type	Generated by	Description
paymentId	string	system	UUID for the payment
accountId	string	system	UUID for the account
paymentNumber	number	user or system	User's ID number for the payment
paymentExternalKey	string	user or system	Optional external key
authAmount	string	system	Total amount authorized (see below)
capturedAmount	string	system	Total amount captured (see below)
purchasedAmount	string	system	Total amount purchased (see below)
refundedAmount	string	system	Total amount refunded (see below)
creditedAmount	string	system	Total amount credited (see below)
currency	string	user or system	Currency associated with the account
paymentMethodId	string	system	UUID for the payment method
transactions	list	system	PaymentTransactions associated with this payment (see below)
paymentAttempts	list	system	Payment retries (see below)

• authAmount: Total amount that is authorized for this payment. Often this is the amount authorized by a single AUTHORIZATION Payment Transaction.

• capturedAmount: Total amount that has been captured (that is, successfully paid).

• purchasedAmount: Total amount that has been purchased. A PURCHASE transaction combines authorization and capture.

• refundedAmount: Total amount that has been refunded.

• creditedAmount: Total amount that has been credited.

• paymentAttempts: Number of payment attempts; this is only effective when the system has been configured to retry failed transactions.

The attributes for a PaymentTransaction are described here.

Payments

These endpoints initiate transactions on an existing Payment. To begin a new Payment, see Trigger a Payment in the Account API.

Capture an existing authorization [using paymentId]

Attempts to capture a payment amount based on a prior authorization. The Payment is identified by its paymentId provided as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "amount": 5
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("33eae7eb-0ad4-45d6-a12a-940e0b460be4");

PaymentTransaction captureTransaction = new PaymentTransaction();
captureTransaction.setPaymentId(paymentId);
captureTransaction.setAmount(BigDecimal.ONE);
captureTransaction.setCurrency(Currency.USD);
captureTransaction.setPaymentExternalKey("d86ecaaa-10ad-4b00-afa8-e469dd3d4bb3");
captureTransaction.setTransactionExternalKey("9cc6ebab-9a92-44f1-a0dc-e111aa7c368d");

ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment capturedPayment = paymentApi.captureAuthorization(paymentId, 
                                                          captureTransaction, 
                                                          NULL_PLUGIN_NAMES, 
                                                          NULL_PLUGIN_PROPERTIES, 
                                                          requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "b2a187b8-0028-4de8-b349-0ebe4e714a5a"
transaction.amount     = "483.22"
transaction.currency   = "BTC"

transaction.capture(user, 
                    reason, 
                    comment, 
                    options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'b2a187b8-0028-4de8-b349-0ebe4e714a5a'
body = PaymentTransaction(payment_id=payment_id, 
                          amount=50.0, 
                          currency='USD')

paymentApi.capture_authorization(payment_id,
                                 body,
                                 created_by,
                                 api_key,
                                 api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@e53497ae
    accountId: c810059c-e90d-4cad-ba19-74acefd783b8
    paymentId: 33eae7eb-0ad4-45d6-a12a-940e0b460be4
    paymentNumber: 1
    paymentExternalKey: d86ecaaa-10ad-4b00-afa8-e469dd3d4bb3
    authAmount: 10.00
    capturedAmount: 1.00
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 30456139-9a6f-4abc-aa21-08ce115a150f
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@70dc2d6
        transactionId: 6c723fdd-1cd8-4515-8228-6b990af63c5d
        transactionExternalKey: 9cc6ebab-9a92-44f1-a0dc-e111aa7c368d
        paymentId: 33eae7eb-0ad4-45d6-a12a-940e0b460be4
        paymentExternalKey: d86ecaaa-10ad-4b00-afa8-e469dd3d4bb3
        transactionType: AUTHORIZE
        amount: 10.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:09.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@af3af9a3
        transactionId: 518c64b6-e863-494b-ad74-ba4fd2c0e768
        transactionExternalKey: cdfd3aa2-362e-4cd1-927e-c4ca517a432a
        paymentId: 33eae7eb-0ad4-45d6-a12a-940e0b460be4
        paymentExternalKey: d86ecaaa-10ad-4b00-afa8-e469dd3d4bb3
        transactionType: CAPTURE
        amount: 1.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:26.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"fc82dba5-69e0-492c-be50-bc7e1642f987",
   "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
   "paymentNumber":"63",
   "paymentExternalKey":"payment1-323475",
   "authAmount":240922.1504832,
   "capturedAmount":483.22,
   "purchasedAmount":0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"BTC",
   "paymentMethodId":"395cfcd1-7a7d-40a6-bc5d-f722833072d2",
   "transactions":[
      {
         "transactionId":"41c95fbc-c9a2-4981-a7ef-7f16f20055ae",
         "transactionExternalKey":"payment1-323475-auth1",
         "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
         "paymentExternalKey":"payment1-323475",
         "transactionType":"AUTHORIZE",
         "amount":240922.1504832,
         "currency":"BTC",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":240922.1504832,
         "processedCurrency":"BTC",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"a6afaec2-4e6f-4e4c-af94-9a03c39c6032",
         "transactionExternalKey":"payment1-323475-capture1",
         "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
         "paymentExternalKey":"payment1-323475",
         "transactionType":"CAPTURE",
         "amount":483.22,
         "currency":"BTC",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":483.22,
         "processedCurrency":"BTC",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A PaymentTransaction object containing, as a minimum, the amount to be captured.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. A PaymentTransaction of type CAPTURE is created.

Capture an existing authorization [using paymentExternalKey]

Requests a payment amount based on a prior authorization. The payment is identified by its external key given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "paymentExternalKey",
          "amount": 1
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments'     

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

PaymentTransaction captureTransaction = new PaymentTransaction();
captureTransaction.setAmount(BigDecimal.ONE);
captureTransaction.setCurrency(Currency.USD);
captureTransaction.setPaymentExternalKey("8e0c507a-05f9-4572-a57d-3f742cdc040d");
captureTransaction.setTransactionExternalKey("9b4dbbe7-749d-4c96-a2e7-57b8bff3bf05");

ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment capturedPayment2 = paymentApi.captureAuthorizationByExternalKey(captureTransaction, 
                                                                        NULL_PLUGIN_NAMES, 
                                                                        NULL_PLUGIN_PROPERTIES, 
                                                                        requestOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.amount                   = "483.22"
transaction.currency                 = "BTC"
transaction.transaction_external_key = "payment1-323475"

transaction.capture(user, 
                    reason, 
                    comment, 
                    options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0,
                          currency='USD')

paymentApi.capture_authorization_by_external_key(body, 
                                                 created_by, 
                                                 api_key, 
                                                 api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@1fcfe41c
    accountId: 01792680-3c3c-4d4f-9ac4-51b82c1f76e8
    paymentId: f0f6129d-f236-4d6c-93b6-63c8fcf7b7a5
    paymentNumber: 1
    paymentExternalKey: 8e0c507a-05f9-4572-a57d-3f742cdc040d
    authAmount: 10.00
    capturedAmount: 2.00
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: bd24759f-b403-443a-bc5b-1fe6a18fa2f3
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@e42a70ce
        transactionId: fddec163-6fb7-42f5-9b8f-20ae7b63dbf4
        transactionExternalKey: 27427503-7be2-4e61-b188-08480f72565f
        paymentId: f0f6129d-f236-4d6c-93b6-63c8fcf7b7a5
        paymentExternalKey: 8e0c507a-05f9-4572-a57d-3f742cdc040d
        transactionType: AUTHORIZE
        amount: 10.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:07.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@2dacb8e7
        transactionId: 702f6edf-fb9e-4f91-9b6d-0b851a05ea6d
        transactionExternalKey: 9b4dbbe7-749d-4c96-a2e7-57b8bff3bf05
        paymentId: f0f6129d-f236-4d6c-93b6-63c8fcf7b7a5
        paymentExternalKey: 8e0c507a-05f9-4572-a57d-3f742cdc040d
        transactionType: CAPTURE
        amount: 1.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:08.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@867e1b5f
        transactionId: f1b753c7-76aa-4584-8a91-6c2990dd9bda
        transactionExternalKey: 5c2dc6ae-ae71-4882-ab57-b29d47a54cc0
        paymentId: f0f6129d-f236-4d6c-93b6-63c8fcf7b7a5
        paymentExternalKey: 8e0c507a-05f9-4572-a57d-3f742cdc040d
        transactionType: CAPTURE
        amount: 1.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:17.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"fc82dba5-69e0-492c-be50-bc7e1642f987",
   "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
   "paymentNumber":"63",
   "paymentExternalKey":"payment1-323475",
   "authAmount":483.22,
   "capturedAmount":483.22,
   "purchasedAmount":0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"BTC",
   "paymentMethodId":"395cfcd1-7a7d-40a6-bc5d-f722833072d2",
   "transactions":[
      {
         "transactionId":"41c95fbc-c9a2-4981-a7ef-7f16f20055ae",
         "transactionExternalKey":"payment1-323475-auth1",
         "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
         "paymentExternalKey":"payment1-323475",
         "transactionType":"AUTHORIZE",
         "amount":483.22,
         "currency":"BTC",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":483.22,
         "processedCurrency":"BTC",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"a6afaec2-4e6f-4e4c-af94-9a03c39c6032",
         "transactionExternalKey":"payment1-323475-capture1",
         "paymentId":"b2a187b8-0028-4de8-b349-0ebe4e714a5a",
         "paymentExternalKey":"payment1-323475",
         "transactionType":"CAPTURE",
         "amount":483.22,
         "currency":"BTC",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":483.22,
         "processedCurrency":"BTC",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A PaymentTransaction object containing, as a minimum, the paymentExternalKey and theamount to be captured.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body. A paymentTransaction of type CAPTURE is created.

Retrieve a payment [using paymentId]

Retrieves a Payment object based on its paymentId given as a path parameter.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}

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/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = true; // Will reflect payment attempts
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.getPayment(paymentId, 
                                        withPluginInfo, 
                                        withAttempts, 
                                        NULL_PLUGIN_PROPERTIES, 
                                        AuditLevel.NONE, 
                                        requestOptions);

payment_id = "12c70604-cede-4df3-a321-38be4d176e9a"
with_plugin_info = false
with_attempts = false

KillBillClient::Model::Payment.find_by_id(payment_id, 
                                          with_plugin_info, 
                                          with_attempts, 
                                          options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e'

paymentApi.get_payment(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
{
  "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
  "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
  "paymentNumber": "14",
  "paymentExternalKey": "paymentExternalKey",
  "authAmount": 1,
  "capturedAmount": 6,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
  "transactions": [
    {
      "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
      "paymentExternalKey": "paymentExternalKey",
      "transactionType": "AUTHORIZE",
      "amount": 1,
      "currency": "USD",
      "effectiveDate": "2018-07-19T16:39:00.000Z",
      "processedAmount": 1,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class Payment {
    org.killbill.billing.client.model.gen.Payment@b45dd4ce
    accountId: c468fd02-8c07-4dad-b11a-a0daf927a4b9
    paymentId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    paymentNumber: 1
    paymentExternalKey: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 0ccbb24b-6279-43ab-9322-bdf07f18b601
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@d7a9d32e
        transactionId: 03be8f74-0ca9-479a-993d-e6fbb35af281
        transactionExternalKey: 03be8f74-0ca9-479a-993d-e6fbb35af281
        paymentId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
        paymentExternalKey: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:04.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: PAYMENT_FAILURE
        gatewayErrorCode: gatewayErrorCode
        gatewayErrorMsg: gatewayError
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: [class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@da337892
        accountId: c468fd02-8c07-4dad-b11a-a0daf927a4b9
        paymentMethodId: 0ccbb24b-6279-43ab-9322-bdf07f18b601
        paymentExternalKey: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
        transactionId: 03be8f74-0ca9-479a-993d-e6fbb35af281
        transactionExternalKey: 03be8f74-0ca9-479a-993d-e6fbb35af281
        transactionType: PURCHASE
        effectiveDate: 2012-09-26T00:00:04.000Z
        stateName: RETRIED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: 052a9fae-2bc5-44e0-81da-181aae56d869
            isUpdatable: false
        }]
        auditLogs: []
    }, class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@c492f721
        accountId: c468fd02-8c07-4dad-b11a-a0daf927a4b9
        paymentMethodId: 0ccbb24b-6279-43ab-9322-bdf07f18b601
        paymentExternalKey: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
        transactionId: null
        transactionExternalKey: 03be8f74-0ca9-479a-993d-e6fbb35af281
        transactionType: PURCHASE
        effectiveDate: 2012-10-04T00:00:05.000Z
        stateName: SCHEDULED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: 052a9fae-2bc5-44e0-81da-181aae56d869
            isUpdatable: false
        }]
        auditLogs: []
    }]
    auditLogs: []
}

{
   "accountId":"7fd39735-87a2-4190-84a0-d28a53347bd4",
   "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
   "paymentNumber":"65",
   "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":50.0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"c8d9199f-c62d-46d3-b94e-1544bbe2a5c9",
   "transactions":[
      {
         "transactionId":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
         "transactionExternalKey":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
         "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
         "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"dff69d54-9593-4d19-893e-287720272175",
         "transactionExternalKey":"dff69d54-9593-4d19-893e-287720272175",
         "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
         "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
         "transactionType":"REFUND",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:06.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

{'account_id': '1686f19d-bc3a-4a4b-987f-837b0547df50',
 'audit_logs': [],
 'auth_amount': 50.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e',
 'payment_id': 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e',
 'payment_method_id': '54c9a68e-155d-44ec-b5a0-694f9a4e0962',
 'payment_number': '428',
 'purchased_amount': 0.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 15, 58, 4, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e',
                   'payment_id': 'ce88ae5b-7ec0-4e14-9ea1-fffe4411278e',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '0eff43b1-133e-4a8b-ab75-061d72a1879c',
                   'transaction_id': '0eff43b1-133e-4a8b-ab75-061d72a1879c',
                   'transaction_type': 'AUTHORIZE'}]}

Query Parameters

Name	Type	Required	Default	Description
withPluginInfo	boolean	no	false	If true, include plugin info
withAttempts	boolean	no	false	If true, include payment attempts
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Retrieve a payment [using paymentExternalKey]

Retrieves a Payment object based on its external key given as a query parameter.

HTTP Request

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

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/payments?externalKey=paymentExternalKey' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String externalPaymentKey = "11b28b2e-a377-4b95-b712-d71cbcb28f80";
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = false; // Will not reflect payment attempts
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payment payment = paymentApi.getPaymentByExternalKey(externalPaymentKey,
                                                     withPluginInfo, 
                                                     withAttempts, 
                                                     NULL_PLUGIN_PROPERTIES, 
                                                     AuditLevel.NONE, 
                                                     requestOptions);` `

external_key = "example_payment_external_key"
with_plugin_info = false
with_attempts = false

KillBillClient::Model::Payment.find_by_external_key(external_key, 
                                                    with_plugin_info, 
                                                    with_attempts, 
                                                    options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key' 

paymentApi.get_payment_by_external_key(payment_external_key,
                                       api_key,
                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
{
  "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
  "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
  "paymentNumber": "14",
  "paymentExternalKey": "paymentExternalKey",
  "authAmount": 1,
  "capturedAmount": 6,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
  "transactions": [
    {
      "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
      "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
      "paymentExternalKey": "paymentExternalKey",
      "transactionType": "AUTHORIZE",
      "amount": 1,
      "currency": "USD",
      "effectiveDate": "2018-07-19T16:39:00.000Z",
      "processedAmount": 1,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class Payment {
    org.killbill.billing.client.model.gen.Payment@d49bf96c
    accountId: e13ed77c-79a8-4cb5-9fbf-66d053920d14
    paymentId: 48f8bc99-43a7-4d79-980c-24cfa8d0c2f4
    paymentNumber: 1
    paymentExternalKey: 11b28b2e-a377-4b95-b712-d71cbcb28f80
    authAmount: 10.00
    capturedAmount: 2.00
    purchasedAmount: 0
    refundedAmount: 2.00
    creditedAmount: 0
    currency: USD
    paymentMethodId: 14b727a5-794b-4ea8-82da-5942f54f6432
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@cf9f2f67
        transactionId: 39b27abc-a657-4b10-838d-7c69dba49853
        transactionExternalKey: 9bf756e6-e758-4092-a2b5-faa1c4e74038
        paymentId: 48f8bc99-43a7-4d79-980c-24cfa8d0c2f4
        paymentExternalKey: 11b28b2e-a377-4b95-b712-d71cbcb28f80
        transactionType: AUTHORIZE
        amount: 10.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:04.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@11a2380d
        transactionId: d67d8daf-1bb3-495a-9d9f-020f51a152a2
        transactionExternalKey: f1895ba0-3b53-45b4-8ae1-64c9e9618dea
        paymentId: 48f8bc99-43a7-4d79-980c-24cfa8d0c2f4
        paymentExternalKey: 11b28b2e-a377-4b95-b712-d71cbcb28f80
        transactionType: CAPTURE
        amount: 1.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:05.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@7a6b1a43
        transactionId: 2ead1581-22c1-4a69-a576-8df55e765071
        transactionExternalKey: 1e968315-f363-42fb-b9e8-3ea3cbf0fc84
        paymentId: 48f8bc99-43a7-4d79-980c-24cfa8d0c2f4
        paymentExternalKey: 11b28b2e-a377-4b95-b712-d71cbcb28f80
        transactionType: CAPTURE
        amount: 1.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:05.000Z
        processedAmount: 1.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@1606355a
        transactionId: 8a50cc62-9063-4581-a9ab-320dc1b8f0c9
        transactionExternalKey: 0942d27a-0d38-498e-a58d-0733b70454c7
        paymentId: 48f8bc99-43a7-4d79-980c-24cfa8d0c2f4
        paymentExternalKey: 11b28b2e-a377-4b95-b712-d71cbcb28f80
        transactionType: REFUND
        amount: 2.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:06.000Z
        processedAmount: 2.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"7fd39735-87a2-4190-84a0-d28a53347bd4",
   "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
   "paymentNumber":"65",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":50.0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"c8d9199f-c62d-46d3-b94e-1544bbe2a5c9",
   "transactions":[
      {
         "transactionId":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
         "transactionExternalKey":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
         "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
         "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"dff69d54-9593-4d19-893e-287720272175",
         "transactionExternalKey":"dff69d54-9593-4d19-893e-287720272175",
         "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
         "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
         "transactionType":"REFUND",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:06.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

{'account_id': '35e08817-3fcd-46a2-aa35-148bbe47c2d9',
 'audit_logs': [],
 'auth_amount': 50.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': 'sample_external_key',
 'payment_id': '14002a0b-3b78-4c94-9297-6b79fe805d0c',
 'payment_method_id': '41cc673a-2030-4ad1-ad91-0a2a22b8732b',
 'payment_number': '430',
 'purchased_amount': 0.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 17, 14, 32, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '14002a0b-3b78-4c94-9297-6b79fe805d0c',
                   'payment_id': '14002a0b-3b78-4c94-9297-6b79fe805d0c',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '8c0bfe29-44b2-4aaf-937a-e368c233dccf',
                   'transaction_id': '8c0bfe29-44b2-4aaf-937a-e368c233dccf',
                   'transaction_type': 'AUTHORIZE'}]}

Query Parameters

Name	Type	Required	Default	Description
externalKey	string	yes	none	Payment external key
withPluginInfo	boolean	no	false	If true, include plugin info
withAttempts	boolean	no	false	If true, include payment attempts
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Complete an existing transaction [using paymentId]

Completes any existing PaymentTransaction that is in a PENDING state, based on its paymentId given as a path parameter.

HTTP Request

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

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);

ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.completeTransaction(paymentId, 
                               body, 
                               NULL_PLUGIN_NAMES, 
                               NULL_PLUGIN_PROPERTIES, 
                               requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "7dcda896-808b-414c-aad4-74ddc98e3dcb"
refresh_options        = nil

transaction.complete_initial_transaction(user, 
                                         reason, 
                                         comment, 
                                         options, 
                                         refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = '7dcda896-808b-414c-aad4-74ddc98e3dcb'
body = PaymentTransaction(payment_id=payment_id)

paymentApi.complete_transaction(payment_id,
                                body,
                                created_by,
                                api_key,
                                api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

{
   "accountId":"f25f5fe5-63ab-4478-89f1-cc868982f19a",
   "paymentId":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
   "paymentNumber":"84",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"0c6f5c90-3b90-4a35-b378-c22a2bea598b",
   "transactions":[
      {
         "transactionId":"bfc95df3-fbaa-427d-a398-fe66c319a55b",
         "transactionExternalKey":"bfc95df3-fbaa-427d-a398-fe66c319a55b",
         "paymentId":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
         "paymentExternalKey":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Query Parameters

None.

Returns

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

Complete an existing transaction [using paymentExternalKey]

Completes any existing PaymentTransaction that is in a PENDING state, based on its paymentExternalKey given in the request body.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/payments

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "paymentExternalKey"
      }' \
    'http://127.0.0.1:8080/1.0/kb/payments' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String externalPaymentKey = "11b28b2e-a377-4b95-b712-d71cbcb28f80";
ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey(externalPaymentKey);

paymentApi.completeTransactionByExternalKey(body, 
                                            NULL_PLUGIN_NAMES, 
                                            NULL_PLUGIN_PROPERTIES, 
                                            requestOptions);

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
refresh_options                  = nil

transaction.complete_initial_transaction(user, 
                                         reason, 
                                         comment, 
                                         options, 
                                         refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key)

paymentApi.complete_transaction_by_external_key(body,
                                                created_by,
                                                api_key,
                                                api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

{
   "accountId":"f25f5fe5-63ab-4478-89f1-cc868982f19a",
   "paymentId":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
   "paymentNumber":"84",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"0c6f5c90-3b90-4a35-b378-c22a2bea598b",
   "transactions":[
      {
         "transactionId":"bfc95df3-fbaa-427d-a398-fe66c319a55b",
         "transactionExternalKey":"bfc95df3-fbaa-427d-a398-fe66c319a55b",
         "paymentId":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
         "paymentExternalKey":"7dcda896-808b-414c-aad4-74ddc98e3dcb",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A Payment object containing, at least, the paymentExternalKey

Query Parameters

None.

Returns

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

Void an existing payment [using paymentId]

Voids a Payment, providing it is in a voidable state. For example, a Payment with only an AUTHORIZE transaction can be voided. No further transactions are possible on a voided Payment. The Payment is identified by its paymentId, which is given as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d'    

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);

ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.voidPayment(paymentId, 
                       body, 
                       NULL_PLUGIN_NAMES, 
                       NULL_PLUGIN_PROPERTIES, 
                       requestOptions);

transaction             = KillBillClient::Model::Transaction.new
transaction.payment_id  = "29b34a3d-d301-4e57-8fc2-2c0a201c4fd0"

transaction.void(user, 
                 reason, 
                 comment, 
                 options)

paymentApi = killbill.api.PaymentApi()
payment_id = '29b34a3d-d301-4e57-8fc2-2c0a201c4fd0'
body = PaymentTransaction(payment_id=payment_id)

paymentApi.void_payment(payment_id,
                        body,
                        created_by,
                        api_key,
                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

{
   "transactionId":"29b34a3d-d301-4e57-8fc2-2c0a201c4fd0",
   "transactionExternalKey":"payment2-121268-void",
   "paymentId":"275889ca-60aa-4801-9b53-8b2e0b9844ca",
   "paymentExternalKey":"payment2-121268",
   "transactionType":"VOID",
   "effectiveDate":"2013-08-01T06:00:07.000Z",
   "processedAmount":0.0,
   "status":"SUCCESS",
   "auditLogs":[]
}

no content

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. a PaymentTransaction of type VOID is created.

Void an existing payment [using paymentExternalKey]

Voids a Payment, providing it is in a voidable state. For example, a Payment with only an AUTHORIZE transaction can be voided. can be voided. No further transactions are possible on a voided payment. The payment is identified by its paymentExternalKey, which is given as a query parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "paymentExternalKey"
      }' \
    'http://127.0.0.1:8080/1.0/kb/payments'     

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String paymentExternalKey = "cca08349-8b26-41c7-bfcc-2e3cf70a0f28";
PaymentTransaction body = new PaymentTransaction();
body.setPaymentExternalKey(paymentExternalKey);

ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

paymentApi.voidPaymentByExternalKey(body, 
                                    NULL_PLUGIN_NAMES, 
                                    NULL_PLUGIN_PROPERTIES, 
                                    requestOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "payment2-121268-void"

transaction.void(user, 
                 reason, 
                 comment, 
                 options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key)

paymentApi.void_payment_by_external_key(body,
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

{
   "transactionId":"29b34a3d-d301-4e57-8fc2-2c0a201c4fd0",
   "transactionExternalKey":"payment2-121268-void",
   "paymentId":"275889ca-60aa-4801-9b53-8b2e0b9844ca",
   "paymentExternalKey":"payment2-121268",
   "transactionType":"VOID",
   "effectiveDate":"2013-08-01T06:00:07.000Z",
   "processedAmount":0.0,
   "status":"SUCCESS",
   "auditLogs":[]
}

no content

Request Body

A Payment object containing, at least, the paymentExternalKey.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A PaymentTransaction of type VOID is created.

Record a chargeback [using paymentId]

Creates a CHARGEBACK PaymentTransaction for a specified Payment. The Payment is identified by its paymentId given as a path parameter. The captured amount is reduced by the chargeback amount.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/chargebacks

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "amount": 5
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/chargebacks' 

TODO

transaction                = KillBillClient::Model::Transaction.new
transaction.payment_id     = "42ab1653-051f-416c-8c70-bf5d4061d4fa"
transaction.amount         = '50.0'
transaction.currency       = 'USD'
transaction.effective_date = nil
refresh_options            = nil

transaction.chargeback(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = '42ab1653-051f-416c-8c70-bf5d4061d4fa'
body = PaymentTransaction(payment_id=payment_id,
                          amount=50.0,
                          currency='USD',
                          effective_date=None)

paymentApi.chargeback_payment(payment_id,
                              body,
                              created_by,
                              api_key,
                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

{
   "accountId":"82d3625e-65f0-403e-a3aa-8077accb4295",
   "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
   "paymentNumber":"67",
   "paymentExternalKey":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":0.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"bde4c67d-4069-4d1c-bd46-029ddda0532f",
   "transactions":[
      {
         "transactionId":"78591b50-a828-456b-a6c2-fefe89a356f3",
         "transactionExternalKey":"78591b50-a828-456b-a6c2-fefe89a356f3",
         "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "paymentExternalKey":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"59d9f016-a63a-4dac-bf9a-0464658d99e1",
         "transactionExternalKey":"59d9f016-a63a-4dac-bf9a-0464658d99e1",
         "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "paymentExternalKey":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A Payment Transaction object containing, at least, the amount.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A Payment Transaction is created with type CHARGEBACK.

Record a chargeback [using paymentExternalKey]

Creates a CHARGEBACK PaymentTransaction for a specified Payment. The Payment is identified by its paymentExternalKey given in the request body. The captured amount is reduced by the chargeback amount.

HTTP Request

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

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "a187746f-841a-481c-8d6c-4497080ed968",
          "amount": 5,
          "currency": "USD"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/chargebacks' 

TODO

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
transaction.amount               = '50.0'
transaction.currency             = 'USD'
transaction.effective_date       = nil
refresh_options                  = nil

transaction.chargeback(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'sample_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0,
                          currency='USD',
                          effective_date=None)

paymentApi.chargeback_payment_by_external_key(body,
                                              created_by,
                                              api_key,
                                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

{
   "accountId":"82d3625e-65f0-403e-a3aa-8077accb4295",
   "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
   "paymentNumber":"67",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":0.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"bde4c67d-4069-4d1c-bd46-029ddda0532f",
   "transactions":[
      {
         "transactionId":"78591b50-a828-456b-a6c2-fefe89a356f3",
         "transactionExternalKey":"78591b50-a828-456b-a6c2-fefe89a356f3",
         "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "paymentExternalKey":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"59d9f016-a63a-4dac-bf9a-0464658d99e1",
         "transactionExternalKey":"59d9f016-a63a-4dac-bf9a-0464658d99e1",
         "paymentId":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "paymentExternalKey":"42ab1653-051f-416c-8c70-bf5d4061d4fa",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A PaymentTransaction object containing, at least, the paymentExternalKey and the amount.

Query Parameters

None.

Returns

If successful, returns a status code of 204 and an empty body. A PaymentTransaction is created with type CHARGEBACK.

Record a chargeback reversal [using paymentId]

Reverses a CHARGEBACK PaymentTransaction, if permitted by the Payment plugin. The chargeback amount is added back to the captured amount. The payment is identified by its paymentId which is given as a path parameter. The CHARGEBACK transaction is identified by its transactionExternalKey which is given in the request body.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/chargebackReversals

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "transactionExternalKey": "7ff346e8-24cc-4437-acfa-c79d96d54ee2"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/chargebackReversals' 

TODO

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "9ceb96a2-5407-482b-8847-7b08cc64213f"
transaction.payment_id               = "74a82e25-120a-4a39-a7f7-7b5c2b4ac05d"

transaction.chargeback_reversals(user, 
                                 reason, 
                                 comment, 
                                 options)

paymentApi = killbill.api.PaymentApi()
payment_id = '74a82e25-120a-4a39-a7f7-7b5c2b4ac05d'
transaction_external_key = '9ceb96a2-5407-482b-8847-7b08cc64213f'
body = PaymentTransaction(payment_id=payment_id,
                          transaction_external_key=transaction_external_key)

paymentApi.chargeback_reversal_payment(payment_id,
                                       body,
                                       created_by,
                                       api_key,
                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

{
   "accountId":"d513c084-2ee4-4e65-aea5-b47dde03d2d4",
   "paymentId":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
   "paymentNumber":"66",
   "paymentExternalKey":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"c5676241-85dd-47ba-be4c-5dec75fade33",
   "transactions":[
      {
         "transactionId":"9ceb96a2-5407-482b-8847-7b08cc64213f",
         "transactionExternalKey":"9ceb96a2-5407-482b-8847-7b08cc64213f",
         "paymentId":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "paymentExternalKey":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"597efe9b-b713-41fb-9ea1-4b2faf80f49c",
         "transactionExternalKey":"597efe9b-b713-41fb-9ea1-4b2faf80f49c",
         "paymentId":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "paymentExternalKey":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"112ad9f1-5a36-447c-aadc-ac20c6e56feb",
         "transactionExternalKey":"597efe9b-b713-41fb-9ea1-4b2faf80f49c",
         "paymentId":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "paymentExternalKey":"74a82e25-120a-4a39-a7f7-7b5c2b4ac05d",
         "transactionType":"CHARGEBACK",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":0.0,
         "status":"PAYMENT_FAILURE",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A PaymentTransaction object containing, at least, the transactionExternalKey.

Query Parameters

None.

Response

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

Record a chargeback reversal [using paymnetExternalKey]

Reverses a CHARGEBACK PaymentTransaction, if permitted by the Payment plugin. The chargeback amount is added back to the captured amount. The Payment is identified by its paymentExternalKey which is given in the request body. The CHARGEBACK transaction is identified by its transactionExternalKey which is also given in the request body.

HTTP Request

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

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "transactionExternalKey": "7ff346e8-24cc-4437-acfa-c79d96d54ee2",
          "paymentExternalKey": "paymentExternalKey",
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/chargebackReversals' 

TODO

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"

transaction.chargeback_reversals(user, 
                                 reason, 
                                 comment, 
                                 options)

paymentApi = killbill.api.PaymentApi()
body = PaymentTransaction(payment_external_key=payment_external_key,
                          transaction_external_key=transaction_external_key)

paymentApi.chargeback_reversal_payment_by_external_key(body,
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

{
   "accountId":"58f01daa-df0f-424e-b430-ad54c3653d70",
   "paymentId":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
   "paymentNumber":"71",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"29b3f923-5985-496e-835a-c26f3742c13d",
   "transactions":[
      {
         "transactionId":"231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c",
         "transactionExternalKey":"231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c",
         "paymentId":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "paymentExternalKey":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"5c9be310-6508-40ff-9553-2b88d1707eef",
         "transactionExternalKey":"5c9be310-6508-40ff-9553-2b88d1707eef",
         "paymentId":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "paymentExternalKey":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"b193f299-9788-4dc9-abc8-b1971bee68e1",
         "transactionExternalKey":"5c9be310-6508-40ff-9553-2b88d1707eef",
         "paymentId":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "paymentExternalKey":"82a8a5eb-7953-4654-b3ff-f3d935ed0c37",
         "transactionType":"CHARGEBACK",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":0.0,
         "status":"PAYMENT_FAILURE",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A PaymentTransaction object containing, at least, the paymentExternalKey and the TransactionExternalKey.

Query Parameters

None.

Response

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

Refund an existing payment [using paymentId]

Refunds part or all of the balance of an existing Payment. The Payment is identified by its paymentId, which is given as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/refunds

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "amount": 5
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/refunds' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("89614849-9bd6-43ba-93d0-e9deb1acf575");

PaymentTransaction body = new PaymentTransaction();
body.setPaymentId(paymentId);
body.setAmount(BigDecimal.TEN);
body.setCurrency(Currency.USD);
body.setPaymentExternalKey("de924e98-2c76-4e90-b9d6-2ced262bc251");
body.setTransactionExternalKey("c4de33be-1c2b-4cf8-be75-6371f08738de");

Payment refundPayment = paymentApi.refundPayment(paymentId, 
                                                 body, 
                                                 NULL_PLUGIN_NAMES, 
                                                 pluginProperties, 
                                                 requestOptions);

transaction            = KillBillClient::Model::Transaction.new
transaction.payment_id = "dce5b2a0-0f0f-430b-9427-545ba4be5c7f"
transaction.amount     = '50.0'
refresh_options        = nil

transaction.refund(user, 
                   reason, 
                   comment, 
                   options, 
                   refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'dce5b2a0-0f0f-430b-9427-545ba4be5c7f' 
body = PaymentTransaction(payment_id=payment_id,
                          amount=50.0)

paymentApi.refund_payment(payment_id,
                          body,
                          created_by,
                          api_key,
                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@deaa66b1
    accountId: 73a443d6-e145-4db3-9c86-f0d53374846c
    paymentId: 89614849-9bd6-43ba-93d0-e9deb1acf575
    paymentNumber: 1
    paymentExternalKey: de924e98-2c76-4e90-b9d6-2ced262bc251
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 10.00
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 92b3c0bf-f5f0-4be0-aad0-c2fd419561cf
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@f6a5a1e2
        transactionId: 1848bd1f-dbb8-4e7b-bd48-d6763ef86932
        transactionExternalKey: c4de33be-1c2b-4cf8-be75-6371f08738de
        paymentId: 89614849-9bd6-43ba-93d0-e9deb1acf575
        paymentExternalKey: de924e98-2c76-4e90-b9d6-2ced262bc251
        transactionType: PURCHASE
        amount: 10.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:02.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@cd051079
        transactionId: ec26f9bf-8b32-493c-9dfe-15188c0f24c7
        transactionExternalKey: c81aa30a-48e3-4150-9789-d4585e95353f
        paymentId: 89614849-9bd6-43ba-93d0-e9deb1acf575
        paymentExternalKey: de924e98-2c76-4e90-b9d6-2ced262bc251
        transactionType: REFUND
        amount: 10.00
        currency: USD
        effectiveDate: 2012-08-25T00:00:32.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: PENDING
        gatewayErrorCode: gatewayErrorCode
        gatewayErrorMsg: gatewayError
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "accountId":"6c297750-3a6d-42a4-9d75-c900fbc75ddf",
   "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
   "paymentNumber":"69",
   "paymentExternalKey":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":50.0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"ba2b0bd4-43f2-4b4a-839c-5a2fa40ea0de",
   "transactions":[
      {
         "transactionId":"d58f9801-e0e6-4b8d-99fb-e19f5b29a313",
         "transactionExternalKey":"d58f9801-e0e6-4b8d-99fb-e19f5b29a313",
         "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "paymentExternalKey":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"28740a66-834a-4005-81d5-55a4550751b9",
         "transactionExternalKey":"28740a66-834a-4005-81d5-55a4550751b9",
         "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "paymentExternalKey":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "transactionType":"REFUND",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A Payment object including, as a minimum, the amount to be refunded.

Query Parameters

None.

Returns

If successful, returns a status code of 201 and an empty body. A new paymentTransaction of type REFUND is created.

Refund an existing payment [using paymentExternalKey]

Refunds part or all of the balance of an existing payment. The payment is identified by its paymentExternalKey, which is given in the request body.

HTTP Request

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

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "paymentExternalKey": "paymentExternalKey",
          "amount": 5,
          "currency": "USD"
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/refunds' 

TODO

transaction                      = KillBillClient::Model::Transaction.new
transaction.payment_external_key = "example_payment_external_key"
transaction.amount               = '50.0'
refresh_options                  = nil

transaction.refund_by_external_key(user, 
                                   reason, 
                                   comment, 
                                   options, 
                                   refresh_options)

paymentApi = killbill.api.PaymentApi()
payment_external_key = 'example_payment_external_key'
body = PaymentTransaction(payment_external_key=payment_external_key,
                          amount=50.0)

paymentApi.refund_payment_by_external_key(body,
                                          created_by,
                                          api_key,
                                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

{
   "accountId":"6c297750-3a6d-42a4-9d75-c900fbc75ddf",
   "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
   "paymentNumber":"69",
   "paymentExternalKey":"example_payment_external_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":50.0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"ba2b0bd4-43f2-4b4a-839c-5a2fa40ea0de",
   "transactions":[
      {
         "transactionId":"d58f9801-e0e6-4b8d-99fb-e19f5b29a313",
         "transactionExternalKey":"d58f9801-e0e6-4b8d-99fb-e19f5b29a313",
         "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "paymentExternalKey":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"28740a66-834a-4005-81d5-55a4550751b9",
         "transactionExternalKey":"28740a66-834a-4005-81d5-55a4550751b9",
         "paymentId":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "paymentExternalKey":"dce5b2a0-0f0f-430b-9427-545ba4be5c7f",
         "transactionType":"REFUND",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

A payment object including, as a minimum, the paymentExternalKey and the amount to be refunded.

Query Parameters

None.

Returns

If successful, returns a status code of 201 and an empty body. A new PaymentTransaction of type REFUND is created.

Cancel a scheduled payment attempt retry [using transactionId]

Cancels a scheduled attempt to retry a PaymentTransaction. The transaction is identified by its transactionId, which is provided as a path parameter.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentTransactionId}/cancelScheduledPaymentTransaction

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/payments/208d38df-8d5a-4e20-89df-15db4b3516b4/cancelScheduledPaymentTransaction'  

TODO

transaction                = KillBillClient::Model::Transaction.new
transaction.transaction_id = "231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c"

transaction.cancel_scheduled_payment(user, 
                                     reason, 
                                     comment, 
                                     options)

paymentApi = killbill.api.PaymentApi()
payment_transaction_id = '231d2bbc-7ce3-4946-b6d9-f24f9a25ff6c'

paymentApi.cancel_scheduled_payment_transaction_by_id(payment_transaction_id,
                                                      created_by,
                                                      api_key,
                                                      api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

Query Parameters

None.

Response

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

Cancel a scheduled payment attempt retry [using transactionExternalKey]

Cancels a scheduled attempt to retry a PaymentTransaction. The transaction is identified by its transactionExternalKey, which is provided in the request body.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/cancelScheduledPaymentTransaction

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/payments/cancelScheduledPaymentTransaction?transactionExternalKey=transaction'    

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String transactionExternalKey = "example_payment_external_key"

paymentApi.cancelScheduledPaymentTransactionByExternalKey(transactionExternalKey, inputOptions);

transaction                          = KillBillClient::Model::Transaction.new
transaction.transaction_external_key = "example_payment_external_key"

transaction.cancel_scheduled_payment(user, 
                                     reason, 
                                     comment, 
                                     options)

paymentApi = killbill.api.PaymentApi()
transaction_external_key = 'example_payment_external_key'

paymentApi.cancel_scheduled_payment_transaction_by_external_key(transaction_external_key,
                                                                created_by,
                                                                api_key,
                                                                api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Request Body

A payment transaction object including, as a minimum, the transactionExternalKey.

Query Parameters

None.

Response

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

Combo api to create a new payment transaction on a existing (or not) account

This API creates a PaymentTransaction of type AUTHORIZE, PURCHASE, or CREDIT. This is the same as the API Trigger a Payment described with the Account endpoints. However, this API can optionally create a new Account and register a new PaymentMethod at the same time.

HTTP Request

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

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 'X-Killbill-CreatedBy: demo' \
    -d '{
            "account": 
            {
                "name": "John Doe"
            },
            "paymentMethod": 
            {
                "pluginName": "__EXTERNAL_PAYMENT__"
            },
            "transaction":
            {
                "transactionExternalKey": "somedTransactionExternalKey",
                "transactionType": "AUTHORIZE",
                "amount": 5,
                "currency": "USD"
            }
        }' \
    'http://127.0.0.1:8080/1.0/kb/payments/combo' 

import org.killbill.billing.client.api.gen.AccountApi;
import org.killbill.billing.client.api.gen.PaymentApi;
protected AccountApi accountApi;
protected PaymentApi paymentApi;

UUID accountId = UUID.fromString("864c1418-e768-4cd5-a0db-67537144b685");
Boolean accountWithBalance = false; // Will not include account balance
Boolean accountWithBalanceAndCBA = false; // Will not include account balance and CBA info

Account account = accountApi.getAccount(accountId, 
                                        accountWithBalance, 
                                        accountWithBalanceAndCBA, 
                                        AuditLevel.NONE, 
                                        requestOptions);

String paymentExternalKey = "5f216d82-dcc4-4e7b-9110-f3896bf6f49a";

ComboPaymentTransaction result = createComboPaymentTransaction(account, paymentExternalKey);

combo_transaction = KillBillClient::Model::ComboTransaction.new
combo_transaction.account = account_obj
combo_transaction.payment_method = payment_method_obj
combo_transaction.transaction = transaction_obj

refresh_options = nil

# Authorization
combo_transaction.auth(user, 
                       reason, 
                       comment, 
                       options, 
                       refresh_options)

# Purchase
combo_transaction.purchase(user, 
                           reason, 
                           comment, 
                           options, 
                           refresh_options)

# Credit
combo_transaction.credit(user, 
                         reason, 
                         comment, 
                         options, 
                         refresh_options)

paymentApi = killbill.api.PaymentApi()
body = ComboPaymentTransaction(account_obj, payment_method_obj, payment_transaction_obj)

paymentApi.create_combo_payment(body,
                                created_by,
                                api_key,
                                api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/5bebc4c3-7c64-404b-8cd4-0a2150279db8/
< Content-Type: application/json
< Content-Length: 0

class ComboPaymentTransaction {
    org.killbill.billing.client.model.gen.ComboPaymentTransaction@631731cc
    account: class Account {
        org.killbill.billing.client.model.gen.Account@9507aa91
        accountId: 864c1418-e768-4cd5-a0db-67537144b685
        name: 1af27661-dec0-4903-ae76-1783ae8f7d11
        firstNameLength: 4
        externalKey: 7cf53480-de54-4428-b72e-789b1c91e13a
        email: aa2c2@da6c8
        billCycleDayLocal: null
        currency: USD
        parentAccountId: null
        isPaymentDelegatedToParent: false
        paymentMethodId: null
        referenceTime: null
        timeZone: UTC
        address1: 12 rue des ecoles
        address2: Poitier
        postalCode: 44 567
        company: Renault
        city: Quelque part
        state: Poitou
        country: France
        locale: fr
        phone: 81 53 26 56
        notes: notes
        isMigrated: false
        accountBalance: null
        accountCBA: null
        auditLogs: []
    }
    paymentMethod: class PaymentMethod {
        org.killbill.billing.client.model.gen.PaymentMethod@1619f5f6
        paymentMethodId: null
        externalKey: 5f216d82-dcc4-4e7b-9110-f3896bf6f49a
        accountId: null
        isDefault: false
        pluginName: noop
        pluginInfo: class PaymentMethodPluginDetail {
            externalPaymentMethodId: null
            isDefaultPaymentMethod: false
            properties: null
        }
        auditLogs: null
    }
    transaction: class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@c4d46526
        transactionId: null
        transactionExternalKey: 2eea894a-2e1e-44e1-942a-eed5a40d3ee0
        paymentId: null
        paymentExternalKey: 2f5fbec7-7f32-493c-a203-d9281f422e72
        transactionType: AUTHORIZE
        amount: 10
        currency: USD
        effectiveDate: null
        processedAmount: null
        processedCurrency: null
        status: null
        gatewayErrorCode: null
        gatewayErrorMsg: null
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: null
    }
    paymentMethodPluginProperties: []
    transactionPluginProperties: []
    auditLogs: null
}

{
   "accountId":"86bb6cbc-1324-47fe-99f6-f0f2bf47f3da",
   "paymentId":"125de719-c4db-4c8c-be98-2a75f0d09011",
   "paymentNumber":"83",
   "paymentExternalKey":"test_key",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"3a61344c-c9b5-4ef6-92cc-581bcb8b20de",
   "transactions":[
      {
         "transactionId":"a93d034b-ef54-4664-88c4-5be20272b330",
         "transactionExternalKey":"a93d034b-ef54-4664-88c4-5be20272b330",
         "paymentId":"125de719-c4db-4c8c-be98-2a75f0d09011",
         "paymentExternalKey":"test_key",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

The request body is a JSON string that represents three distinct objects: account, paymentMethod, and transaction. For example:

{ "account": { }, "paymentMethod": { "pluginName": "EXTERNAL_PAYMENT" "transaction": { "transactionType": "AUTHORIZE", "amount": 500, "currency": "USD" } }

This example assumes that a new Account is to be created.

1. No attributes are required for the account; however if the currency attribute is not given here it must be given for the transaction.

2. If a new account is created, a new paymentMethod must be registered for that account. The only attribute required here is the pluginName.

3. The transaction object contains, as a minimum, the transaction type, the amount, and the currency, unless given with the account.

Query Parameters

None.

Returns

If successful, returns a status code of 201 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 Payment objects. For details on Custom Fields see Custom Field.

Add custom fields to payment

Adds one or more custom fields to a payment object. Existing custom fields are not modified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

paymentApi.createPaymentCustomFields(paymentId, 
                                     customFields, 
                                     requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'PAYMENT'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

payment.add_custom_field(custom_field, 
                         user,
                         reason,
                         comment,
                         options)

paymentApi = killbill.api.PaymentApi()
body = CustomField(name='Test Custom Field', value='test_value')

paymentApi.create_payment_custom_fields(payment_id,
                                        [body],
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: PAYMENT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"PAYMENT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

Request Body

A JSON string representing the custom field object or objects to be added.

Query Parameters

None.

Response

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

Retrieve payment custom fields

Retrieves the custom fields associated with a payment

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/customFields

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/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

List<CustomField> customFields = paymentApi.getPaymentCustomFields(paymentId,
                                                                   AuditLevel.NONE,
                                                                   requestOptions);

audit = 'NONE'

payment.custom_fields(audit, options)

paymentApi = killbill.api.PaymentApi()

paymentApi.get_payment_custom_fields(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "objectType": "PAYMENT",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: PAYMENT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"PAYMENT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '893e0286-2b48-493b-99af-aac9b172dc75',
 'name': 'Test Custom Field',
 'object_id': '924bebe7-58e7-40e8-a5ed-192efb59d8ee',
 'object_type': 'PAYMENT',
 'value': 'test_value'}]

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for a payment

Modifies the custom fields associated with a payment object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

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

paymentApi.modifyPaymentCustomFields(paymentId, 
                                     customFieldModified, 
                                     requestOptions);

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

payment.modify_custom_field(custom_field,                                                                                            
                            user, 
                            reason,
                            comment, 
                            options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
body = CustomField(custom_field_id=custom_field_id, name='Test Modify', value='test_modify_value')

paymentApi.modify_payment_custom_fields(payment_id,
                                        [body],
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Requst Body

A JSON string representing a list of custom fields to substitute for the existing ones.

Query Parameters

None.

Response

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

Remove custom fields from a payment

Removes a specified set of custom fields from a payment object

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/payments/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=e4bac228-872d-4966-8072-2c3ac06442ed' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");

paymentApi.deletePaymentCustomFields(paymentId, 
                                     customFieldsId, 
                                     requestOptions);

custom_field_id = custom_field.id

payment.remove_custom_field(custom_field_id,                                                                                            
                            user, 
                            reason,
                            comment, 
                            options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'

paymentApi.delete_payment_custom_fields(payment_id,
                                        created_by,
                                        api_key,
                                        api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	none	Comma separated list of custom field object IDs that should be deleted.

Response

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

Tags

See Account Tags for an introduction.

The are no system tags applicable to a Payment.

Add tags to a payment

Adds one or more tags to a payment object. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

Tags result = paymentApi.createPaymentTags(paymentId, 
                                           ImmutableList.<UUID>of(tagDefinitionId), 
                                           requestOptions);

tag_name = 'foo'

payment.add_tag(tag_name,
                user,
                reason,
                comment,
                options)

paymentApi = killbill.api.PaymentApi()
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

paymentApi.create_payment_tags(payment_id,
                               tag,
                               created_by,
                               api_key,
                               api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: PAYMENT
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"PAYMENT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

no content

Request Body

Provides a list of tag definition Ids in JSON format

Query Parameters

None.

Response

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

Retrieve payment tags

Retrieves all tags attached to this payment.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/tags

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/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = paymentApi.getPaymentTags(paymentId, 
                                           includedDeleted, 
                                           AuditLevel.FULL, 
                                           requestOptions);

included_deleted = false
audit = 'NONE'

payment.tags(included_deleted,
             audit,
             options)

paymentApi = killbill.api.PaymentApi()
payment_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

paymentApi.get_payment_tags(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "tagId": "890e3b13-3114-478b-9365-50f1a2682143",
    "objectType": "PAYMENT",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "tagDefinitionId": "353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName": "foo",
    "auditLogs": []
  }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: PAYMENT
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"PAYMENT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'object_id': '41b6b214-c3f7-40ea-89cd-6a4ecbd9083b',
 'object_type': 'PAYMENT',
 'tag_definition_id': '353752dd-9041-4450-b782-a8bb03a923c8',
 'tag_definition_name': 'foo',
 'tag_id': '865e0c77-def7-4880-ac80-11c21a5e571d'}]

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted tags
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from a payment

Removes a list of tags attached to an invoice.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/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' \
    'http://127.0.0.1:8080/1.0/kb/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'   

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

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

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

paymentApi.deletePaymentTags(paymentId, 
                             ImmutableList.<UUID>of(tagDefinitionId), 
                             requestOptions);

tag_name = 'TEST'

payment.remove_tag(tag_name,
                   user,
                   reason,
                   comment,
                   options)

paymentApi = killbill.api.PaymentApi()
payment_id = 'dce5b2a0-0f0f-430b-9427-545ba4be5c7f'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"] 

paymentApi.delete_payment_tags(payment_id,
                               created_by,
                               api_key,
                               api_secret,
                               tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of string	yes	none	List of tag definition IDs identifying the tags that should be removed.

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 payment audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified payment. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/auditLogsWithHistory

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/payments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/auditLogsWithHistory' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

UUID paymentId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

List<AuditLog> paymentAuditLogWithHistory = paymentApi.getPaymentAuditLogsWithHistory(paymentId, 
                                                                                      requestOptions);

accountApi = killbill.api.AccountApi()
account_id = 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda'

accountApi.get_account_audit_logs_with_history(account_id, api_key, api_secret)

account.audit_logs_with_history(options)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-19T16:39:00.000Z",
    "objectType": "PAYMENT",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "changedBy": "demo",
    "reasonCode": null,
    "comments": null,
    "userToken": "5d32d0ab-3c08-47b2-8c6d-bb9d2a7fd62c",
    "history": 
    {
      "id": null,
      "createdDate": "2018-07-19T16:39:00.000Z",
      "updatedDate": "2018-07-19T16:39:00.000Z",
      "recordId": 14,
      "accountRecordId": 35,
      "tenantRecordId": 1,
      "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
      "paymentNumber": null,
      "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
      "externalKey": "paymentExternalKey",
      "stateName": null,
      "lastSuccessStateName": null,
      "tableName": "PAYMENTS",
      "historyTableName": "PAYMENT_HISTORY"
    }
  },
]

//First element of the list
class AuditLog {
    changeType: INSERT
    changeDate: 2012-08-25T00:00:02.000Z
    objectType: PAYMENT
    objectId: 5f8d8211-973b-40c2-b996-eb64c545a651
    changedBy: Toto
    reasonCode: i am god
    comments: no comment
    userToken: 2529c9c2-9916-4306-9270-d2bfa8bfb44b
    history: {id=null, 
              createdDate=2012-08-25T00:00:02.000Z, 
              updatedDate=2012-08-25T00:00:02.000Z, 
              recordId=1, 
              accountRecordId=1, 
              tenantRecordId=1, 
              accountId=d6bf4cff-9e13-460f-b375-f71f7daaaa83, 
              paymentNumber=null, 
              paymentMethodId=abd4eb92-5518-4aff-8568-dac97fe81586, 
              externalKey=fa5bb343-ad44-41d3-b6f0-21a61efcbb5b, 
              stateName=null, 
              lastSuccessStateName=null, 
              tableName=PAYMENTS, 
              historyTableName=PAYMENT_HISTORY}
}

[
   {
      "changeType":"INSERT",
      "changeDate":"2013-08-01T06:00:00.000Z",
      "objectType":"ACCOUNT",
      "objectId":"08a1c2e4-687f-48ca-9c38-888108a2ce0a",
      "changedBy":"test_account_tags",
      "userToken":"5c0632c3-6567-4b0b-8e37-e2a9bb9ab6b2",
      "history":{
         "id":null,
         "createdDate":"2013-08-01T06:00:00.000Z",
         "updatedDate":"2013-08-01T06:00:00.000Z",
         "recordId":505,
         "accountRecordId":505,
         "tenantRecordId":822,
         "externalKey":"1527086785-621747",
         "email":"kill@bill.com",
         "name":"KillBillClient",
         "firstNameLength":null,
         "currency":"USD",
         "parentAccountId":null,
         "isPaymentDelegatedToParent":null,
         "billingCycleDayLocal":0,
         "paymentMethodId":null,
         "referenceTime":"2013-08-01T06:00:00.000Z",
         "timeZone":"UTC",
         "locale":"fr_FR",
         "address1":"7, yoyo road",
         "address2":"Apt 5",
         "companyName":"Unemployed",
         "city":"San Francisco",
         "stateOrProvince":"California",
         "country":"US",
         "postalCode":"94105",
         "phone":null,
         "notes":null,
         "migrated":null,
         "tableName":"ACCOUNT",
         "historyTableName":"ACCOUNT_HISTORY"
      }
   }
]

[{'change_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc()),
 'change_type': 'INSERT',
 'changed_by': 'test',
 'comments': None,
 'history': {'created_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc()),
             'id': None,
             'updated_date': datetime.datetime(2018, 5, 23, 14, 43, 41, tzinfo=tzutc())},
 'object_id': 'c62d5f6d-0b57-444d-bf9b-dd23e781fbda',
 'object_type': 'ACCOUNT',
 'reason_code': None,
 'user_token': '40e771bf-160e-4ff6-82be-463f2d9e634d'}]

Query Parameters

None.

Response

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

Retrieve payment attempt audit logs with history by id

Retrieves a list of audit log records showing events that occurred related to a specified payment attempt. History information is included with each record.

Example Request:

Example Response:

Query Parameters

None.

Response

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

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/auditLogsWithHistory

List and Search

These endpoints allow you to list all payments or to search for a specific payment.

Get payments

Retrieve a list of all payments for this tenant.

HTTP Request

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

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/payments/pagination' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

Long offset = 0L;
Long limit = 100L;
String pluginName = null;
Boolean withPluginInfo = false; // Will not fetch plugin info
Boolean withAttempts = true; // Will reflect payment attempts
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = paymentApi.getPayments(offset, 
                                           limit, 
                                           pluginName, 
                                           withPluginInfo, 
                                           withAttempts, 
                                           NULL_PLUGIN_PROPERTIES, 
                                           AuditLevel.NONE, 
                                           requestOptions);

offset = 0
limit = 100
payment.find_in_batches(offset, 
                        limit, 
                        options)

paymentApi = killbill.api.PaymentApi()

paymentApi.get_payments(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "accountId": "ca15adc4-1061-4e54-a9a0-15e773b3b154",
    "paymentId": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
    "paymentNumber": "7",
    "paymentExternalKey": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
    "authAmount": 0,
    "capturedAmount": 0,
    "purchasedAmount": 0,
    "refundedAmount": 0,
    "creditedAmount": 0,
    "currency": "USD",
    "paymentMethodId": "dc89832d-18a3-42fd-b3be-cac074fddb36",
    "transactions": [
      {
        "transactionId": "92935e84-fd79-4672-98bf-df84566153c6",
        "transactionExternalKey": "92935e84-fd79-4672-98bf-df84566153c6",
        "paymentId": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
        "paymentExternalKey": "4634b2ae-5263-4139-99b2-e2005f09a9fd",
        "transactionType": "PURCHASE",
        "amount": 1,
        "currency": "USD",
        "effectiveDate": "2018-07-18T15:04:05.000Z",
        "processedAmount": 0,
        "processedCurrency": "USD",
        "status": "PLUGIN_FAILURE",
        "gatewayErrorCode": "RuntimeError",
        "gatewayErrorMsg": "Could not retrieve the payer info: the token is missing",
        "firstPaymentReferenceId": null,
        "secondPaymentReferenceId": null,
        "properties": null,
        "auditLogs": []
      }
    ],
    "paymentAttempts": null,
    "auditLogs": []
  }
]

//First element of the list
class Payment {
    org.killbill.billing.client.model.gen.Payment@1f07a0c4
    accountId: 7f13319c-0beb-4c6d-9ef3-d26c20b1c183
    paymentId: 2933e208-4bbb-4898-981d-dc487fdc6e1f
    paymentNumber: 1
    paymentExternalKey: 2933e208-4bbb-4898-981d-dc487fdc6e1f
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 8cd62a90-48a7-428d-b360-9804bb85edff
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@50cedfc2
        transactionId: 135100a0-b192-45a0-b8b6-961d31d0b492
        transactionExternalKey: 135100a0-b192-45a0-b8b6-961d31d0b492
        paymentId: 2933e208-4bbb-4898-981d-dc487fdc6e1f
        paymentExternalKey: 2933e208-4bbb-4898-981d-dc487fdc6e1f
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:05.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: PAYMENT_FAILURE
        gatewayErrorCode: gatewayErrorCode
        gatewayErrorMsg: gatewayError
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: [class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@d3d09824
        accountId: 7f13319c-0beb-4c6d-9ef3-d26c20b1c183
        paymentMethodId: 8cd62a90-48a7-428d-b360-9804bb85edff
        paymentExternalKey: 2933e208-4bbb-4898-981d-dc487fdc6e1f
        transactionId: 135100a0-b192-45a0-b8b6-961d31d0b492
        transactionExternalKey: 135100a0-b192-45a0-b8b6-961d31d0b492
        transactionType: PURCHASE
        effectiveDate: 2012-09-26T00:00:05.000Z
        stateName: RETRIED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: dd27083e-6150-41e8-a503-f35f971dc347
            isUpdatable: false
        }]
        auditLogs: []
    }, class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@733e1442
        accountId: 7f13319c-0beb-4c6d-9ef3-d26c20b1c183
        paymentMethodId: 8cd62a90-48a7-428d-b360-9804bb85edff
        paymentExternalKey: 2933e208-4bbb-4898-981d-dc487fdc6e1f
        transactionId: null
        transactionExternalKey: 135100a0-b192-45a0-b8b6-961d31d0b492
        transactionType: PURCHASE
        effectiveDate: 2012-10-04T00:00:05.000Z
        stateName: SCHEDULED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: dd27083e-6150-41e8-a503-f35f971dc347
            isUpdatable: false
        }]
        auditLogs: []
    }]
    auditLogs: []
}

[
    {
       "accountId":"7fd39735-87a2-4190-84a0-d28a53347bd4",
       "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
       "paymentNumber":"65",
       "paymentExternalKey":"example_payment_external_key",
       "authAmount":0,
       "capturedAmount":0,
       "purchasedAmount":50.0,
       "refundedAmount":50.0,
       "creditedAmount":0,
       "currency":"USD",
       "paymentMethodId":"c8d9199f-c62d-46d3-b94e-1544bbe2a5c9",
       "transactions":[
          {
             "transactionId":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
             "transactionExternalKey":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
             "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
             "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
             "transactionType":"PURCHASE",
             "amount":50.0,
             "currency":"USD",
             "effectiveDate":"2013-08-01T06:00:04.000Z",
             "processedAmount":50.0,
             "processedCurrency":"USD",
             "status":"SUCCESS",
             "auditLogs":[]
          },
          {
             "transactionId":"dff69d54-9593-4d19-893e-287720272175",
             "transactionExternalKey":"dff69d54-9593-4d19-893e-287720272175",
             "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
             "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
             "transactionType":"REFUND",
             "amount":50.0,
             "currency":"USD",
             "effectiveDate":"2013-08-01T06:00:06.000Z",
             "processedAmount":50.0,
             "processedCurrency":"USD",
             "status":"SUCCESS",
             "auditLogs":[]
          }
       ],
       "auditLogs":[]
    }
]

[{'account_id': '5b23cc61-4afc-48bd-9fe8-0fafda02a00f',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '9e283f36-269b-4d51-8341-1ff354b8c631',
 'payment_id': '9e283f36-269b-4d51-8341-1ff354b8c631',
 'payment_method_id': '4acc1167-22f9-4c89-a8e7-051814ba78f0',
 'payment_number': '533',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 20, 8, 45, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '9e283f36-269b-4d51-8341-1ff354b8c631',
                   'payment_id': '9e283f36-269b-4d51-8341-1ff354b8c631',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': 'b144e485-7570-4748-b5d2-7c25d720b264',
                   'transaction_id': 'b144e485-7570-4748-b5d2-7c25d720b264',
                   'transaction_type': 'PURCHASE'}]}, {'account_id': '5b23cc61-4afc-48bd-9fe8-0fafda02a00f',
 'audit_logs': [],
 'auth_amount': 50.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '078b62a4-1197-44b1-801d-3a0c01a53702',
 'payment_id': '078b62a4-1197-44b1-801d-3a0c01a53702',
 'payment_method_id': '4acc1167-22f9-4c89-a8e7-051814ba78f0',
 'payment_number': '534',
 'purchased_amount': 0.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 20, 8, 46, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '078b62a4-1197-44b1-801d-3a0c01a53702',
                   'payment_id': '078b62a4-1197-44b1-801d-3a0c01a53702',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '9c184ba0-723b-4d5b-ad57-be26fb15fd40',
                   'transaction_id': '9c184ba0-723b-4d5b-ad57-be26fb15fd40',
                   'transaction_type': 'AUTHORIZE'}]}]

Query Parameters

Name	Type	Required	Default	Description
offset	long	no	0	Starting index for items listed
limit	long	no	100	Maximum number of items to be listed
withPluginInfo	boolean	no	false	if true, include plugin info
withAttempts	boolean	no	false	if true, include payment attempts
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list of all payments for this tenant.

Search payments

Search for a payment using a specified search string. The operation returns all payment records which are matched by the search string.

HTTP Request

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

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/payments/search/8fe697d4-2c25-482c-aa45-f6cd5a48186d' 

import org.killbill.billing.client.api.gen.PaymentApi;
protected PaymentApi paymentApi;

String searchKey = "ccbc67f5-91cb-4b9a-9648-fa6aedaf0890";
Long offset = 0L;
Long limit = 100L;
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = true;  // Will reflect payment attempts
String pluginName = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

Payments payments = paymentApi.searchPayments(searchKey, 
                                              offset, 
                                              limit, 
                                              withPluginInfo, 
                                              withAttempts, 
                                              pluginName, 
                                              NULL_PLUGIN_PROPERTIES, 
                                              AuditLevel.NONE, 
                                              requestOptions);

search_key = 'PURCHASE'
offset = 0
limit = 100

payment.find_in_batches_by_search_key(search_key,
                                      offset,
                                      limit,
                                      options)

paymentApi = killbill.api.PaymentApi()
search_key = 'SUCCESS'

paymentApi.search_payments(search_key, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
    "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "paymentNumber": "14",
    "paymentExternalKey": "paymentExternalKey",
    "authAmount": 1,
    "capturedAmount": 6,
    "purchasedAmount": 0,
    "refundedAmount": 10,
    "creditedAmount": 0,
    "currency": "USD",
    "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
    "transactions": [
      {
        "transactionId": "208d38df-8d5a-4e20-89df-15db4b3516b4",
        "transactionExternalKey": "208d38df-8d5a-4e20-89df-15db4b3516b4",
        "paymentId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
        "paymentExternalKey": "paymentExternalKey",
        "transactionType": "AUTHORIZE",
        "amount": 1,
        "currency": "USD",
        "effectiveDate": "2018-07-19T16:39:00.000Z",
        "processedAmount": 1,
        "processedCurrency": "USD",
        "status": "SUCCESS",
        "gatewayErrorCode": null,
        "gatewayErrorMsg": null,
        "firstPaymentReferenceId": null,
        "secondPaymentReferenceId": null,
        "properties": null,
        "auditLogs": []
      }
    ],
    "paymentAttempts": null,
    "auditLogs": []
  }
]

//First element of the list
class Payment {
    org.killbill.billing.client.model.gen.Payment@9e017939
    accountId: ccbc67f5-91cb-4b9a-9648-fa6aedaf0890
    paymentId: 0f8ecfc9-48f4-48da-a01a-929f5d466351
    paymentNumber: 1
    paymentExternalKey: 0f8ecfc9-48f4-48da-a01a-929f5d466351
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: ac1c90d5-30d4-484e-9da0-918a8fff5f7d
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@dd504973
        transactionId: d4bde19e-299e-402f-8105-3f241cc21db0
        transactionExternalKey: d4bde19e-299e-402f-8105-3f241cc21db0
        paymentId: 0f8ecfc9-48f4-48da-a01a-929f5d466351
        paymentExternalKey: 0f8ecfc9-48f4-48da-a01a-929f5d466351
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:05.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: PAYMENT_FAILURE
        gatewayErrorCode: gatewayErrorCode
        gatewayErrorMsg: gatewayError
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: [class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@a9c18de
        accountId: ccbc67f5-91cb-4b9a-9648-fa6aedaf0890
        paymentMethodId: ac1c90d5-30d4-484e-9da0-918a8fff5f7d
        paymentExternalKey: 0f8ecfc9-48f4-48da-a01a-929f5d466351
        transactionId: d4bde19e-299e-402f-8105-3f241cc21db0
        transactionExternalKey: d4bde19e-299e-402f-8105-3f241cc21db0
        transactionType: PURCHASE
        effectiveDate: 2012-09-26T00:00:05.000Z
        stateName: RETRIED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: 4aafe2fe-0bd0-47d6-b58a-7a12a15ccdea
            isUpdatable: false
        }]
        auditLogs: []
    }, class PaymentAttempt {
        org.killbill.billing.client.model.gen.PaymentAttempt@4d117a78
        accountId: ccbc67f5-91cb-4b9a-9648-fa6aedaf0890
        paymentMethodId: ac1c90d5-30d4-484e-9da0-918a8fff5f7d
        paymentExternalKey: 0f8ecfc9-48f4-48da-a01a-929f5d466351
        transactionId: null
        transactionExternalKey: d4bde19e-299e-402f-8105-3f241cc21db0
        transactionType: PURCHASE
        effectiveDate: 2012-10-04T00:00:05.000Z
        stateName: SCHEDULED
        amount: null
        currency: USD
        pluginName: __INVOICE_PAYMENT_CONTROL_PLUGIN__
        pluginProperties: [class PluginProperty {
            key: IPCD_INVOICE_ID
            value: 4aafe2fe-0bd0-47d6-b58a-7a12a15ccdea
            isUpdatable: false
        }]
        auditLogs: []
    }]
    auditLogs: []
}

[
    {
       "accountId":"7fd39735-87a2-4190-84a0-d28a53347bd4",
       "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
       "paymentNumber":"65",
       "paymentExternalKey":"example_payment_external_key",
       "authAmount":0,
       "capturedAmount":0,
       "purchasedAmount":50.0,
       "refundedAmount":50.0,
       "creditedAmount":0,
       "currency":"USD",
       "paymentMethodId":"c8d9199f-c62d-46d3-b94e-1544bbe2a5c9",
       "transactions":[
          {
             "transactionId":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
             "transactionExternalKey":"a48855a4-bbe5-43d0-9e81-016ca719abeb",
             "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
             "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
             "transactionType":"PURCHASE",
             "amount":50.0,
             "currency":"USD",
             "effectiveDate":"2013-08-01T06:00:04.000Z",
             "processedAmount":50.0,
             "processedCurrency":"USD",
             "status":"SUCCESS",
             "auditLogs":[]
          },
          {
             "transactionId":"dff69d54-9593-4d19-893e-287720272175",
             "transactionExternalKey":"dff69d54-9593-4d19-893e-287720272175",
             "paymentId":"12c70604-cede-4df3-a321-38be4d176e9a",
             "paymentExternalKey":"12c70604-cede-4df3-a321-38be4d176e9a",
             "transactionType":"REFUND",
             "amount":50.0,
             "currency":"USD",
             "effectiveDate":"2013-08-01T06:00:06.000Z",
             "processedAmount":50.0,
             "processedCurrency":"USD",
             "status":"SUCCESS",
             "auditLogs":[]
          }
       ],
       "auditLogs":[]
    }
]

[{'account_id': '494df5a9-d8da-4e56-852a-459fdaca85d1',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '9988364a-3f86-4fcf-8a49-35ba6d1c1a93',
 'payment_id': '9988364a-3f86-4fcf-8a49-35ba6d1c1a93',
 'payment_method_id': 'b7c26570-3515-4055-a8a8-4d6d4b45dc28',
 'payment_number': '537',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 20, 12, 8, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '9988364a-3f86-4fcf-8a49-35ba6d1c1a93',
                   'payment_id': '9988364a-3f86-4fcf-8a49-35ba6d1c1a93',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '0fa4d97d-086b-43b3-a9f2-085c9cc382c2',
                   'transaction_id': '0fa4d97d-086b-43b3-a9f2-085c9cc382c2',
                   'transaction_type': 'PURCHASE'}]}, {'account_id': '494df5a9-d8da-4e56-852a-459fdaca85d1',
 'audit_logs': [],
 'auth_amount': 50.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': 'b937a96e-36b4-46fa-a609-64d568403551',
 'payment_id': 'b937a96e-36b4-46fa-a609-64d568403551',
 'payment_method_id': 'b7c26570-3515-4055-a8a8-4d6d4b45dc28',
 'payment_number': '538',
 'purchased_amount': 0.0,
 'refunded_amount': 0.0,
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 11, 20, 12, 9, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': 'b937a96e-36b4-46fa-a609-64d568403551',
                   'payment_id': 'b937a96e-36b4-46fa-a609-64d568403551',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '49884122-aa64-4518-b2de-55fe4fbde856',
                   'transaction_id': '49884122-aa64-4518-b2de-55fe4fbde856',
                   'transaction_type': 'AUTHORIZE'}]}]

Query Parameters

Name	Type	Required	Default	Description
searchKey	string	yes	none	What you want to find
offset	long	no	0	Starting index for items listed
limit	long	no	100	Maximum number of items to be listed
withPluginInfo	boolean	no	false	if true, include plugin info
withAttempts	boolean	no	false	if true, include payment attempts
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

If successful, returns a status code of 200 and a list of all payments matched with the search key entered.

Payment Transaction

Payment transactions belong to a Payment object.

They represent a particular payment operation, such as authorization, chargeback, refund, etc. Most operations happen at the Payment level, but there are a few endpoints that work directly at the transaction level.

Payment Transaction Resource

A PaymentTransaction is represented by a PaymentTransaction resource object. The attributes for this resource object are as follows:

Name	Type	Generated by	Description
transactionId	string	system	UUID for the transaction
transactionExternalKey	string	user or system	Optional external key
paymentId	string	system	UUID for the payment
paymentExternalKey	string	user or system	Optional external key
transactionType	string	user	Transaction type (see below)
amount	number	system	Total amount of the transaction
currency	string	user or system	Currency associated with the account
effectiveDate	string	user	Effective date of the transaction
processedAmount	number	system	The amount processed by the gateway (see below)
processedCurrency	string	system	The currency processed by the gateay (see below)
status	string	system	Transaction status (see below)
gatewayErrorCode	string	system	Error code returned by the payment gateway
gatewayErrorMsg	string	system	Error message returned by the payment gateway
firstPaymentReferenceId	string	system	Payment gateway reference
secondPaymentReferenceId	string	system	see below
properties	string	user	see below

• transactionType: Possible values are: AUTHORIZE, CAPTURE, CHARGEBACK, CREDIT, PURCHASE, REFUND, VOID

• processedAmount: This will often match amount, but could be different, perhaps due to currency conversion

• processedCurrency: This will often match currency, but could be different, perhaps due to currency conversion

• status: Possible values are: SUCCESS, UNKNOWN, PENDING, PAYMENT_FAILURE, PLUGIN_FAILURE, or PAYMENT_SYSTEM_OFF

• secondPaymentReferenceId: Typically the ID from the actual payment processor, when the gateway is a PSP.

• properties: Plugin-specific properties to be interpreted by the plugin

Payment Transactions

Endpoints to retrieve a PaymentTransaction object or to set the status of a pending transaction. Note that endpoints to generate payment transactions are provided with the Payment APIs.

Retrieve a payment by transaction id

Retrieves a Payment object based on a PaymentTransaction id, which is given as a path parameter

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}

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/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("41f4d299-4371-4876-96b4-0b3cc81b246b");
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = paymentTransactionApi.getPaymentByTransactionId(paymentTransactionId, NULL_PLUGIN_PROPERTIES, requestOptions);

TODO

TODO

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "paymentNumber": "47",
  "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "c02fa9b0-ae95-42ae-9010-bc11cb160947",
  "transactions": [
    {
      "transactionId": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionType": "AUTHORIZE",
      "amount": 0,
      "currency": "USD",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class Payment {
    org.killbill.billing.client.model.gen.Payment@dd818d6d
    accountId: 3093aa3e-63c6-4ffe-92d1-60a0e34f2397
    paymentId: 59f1e0cb-58ae-481a-afbb-6709e86066de
    paymentNumber: 42
    paymentExternalKey: 59f1e0cb-58ae-481a-afbb-6709e86066de
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: aa00971a-6310-43e1-af83-28fca1edadd3
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@c3eadd4f
        transactionId: 41f4d299-4371-4876-96b4-0b3cc81b246b
        transactionExternalKey: 41f4d299-4371-4876-96b4-0b3cc81b246b
        paymentId: 59f1e0cb-58ae-481a-afbb-6709e86066de
        paymentExternalKey: 59f1e0cb-58ae-481a-afbb-6709e86066de
        transactionType: PURCHASE
        amount: 1.00
        currency: USD
        effectiveDate: 2021-05-05T11:54:19.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: UNKNOWN
        gatewayErrorCode: null
        gatewayErrorMsg: null
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

TODO

TODO

Query Parameters

Name	Type	Required	Default	Description
withPluginInfo	boolean	no	false	If true, include plugin info
withAttempts	boolean	no	false	if true, include payment attempts

Response

If successful, returns a status code of 200 and a payment object including the specified transaction.

Retrieve a payment transaction by external key

Retrieve a Payment object based on a PaymentTransaction external key, which is given as a query parameter

HTTP Request

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

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/paymentTransactions?transactionExternalKey=07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

String transactionExternalKey = "41f4d299-4371-4876-96b4-0b3cc81b246b";
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;
Payment payment = paymentTransactionApi.getPaymentByTransactionExternalKey(transactionExternalKey, NULL_PLUGIN_PROPERTIES, requestOptions);

TODO

TODO

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

{
  "accountId": "2ad52f53-85ae-408a-9879-32a7e59dd03d",
  "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "paymentNumber": "47",
  "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 0,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "c02fa9b0-ae95-42ae-9010-bc11cb160947",
  "transactions": [
    {
      "transactionId": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "paymentExternalKey": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionType": "AUTHORIZE",
      "amount": 0,
      "currency": "USD",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class Payment {
    org.killbill.billing.client.model.gen.Payment@dd818d6d
    accountId: 3093aa3e-63c6-4ffe-92d1-60a0e34f2397
    paymentId: 59f1e0cb-58ae-481a-afbb-6709e86066de
    paymentNumber: 42
    paymentExternalKey: 59f1e0cb-58ae-481a-afbb-6709e86066de
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: aa00971a-6310-43e1-af83-28fca1edadd3
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@c3eadd4f
        transactionId: 41f4d299-4371-4876-96b4-0b3cc81b246b
        transactionExternalKey: 41f4d299-4371-4876-96b4-0b3cc81b246b
        paymentId: 59f1e0cb-58ae-481a-afbb-6709e86066de
        paymentExternalKey: 59f1e0cb-58ae-481a-afbb-6709e86066de
        transactionType: PURCHASE
        amount: 1.00
        currency: USD
        effectiveDate: 2021-05-05T11:54:19.000Z
        processedAmount: 0.00
        processedCurrency: USD
        status: UNKNOWN
        gatewayErrorCode: null
        gatewayErrorMsg: null
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

TODO

TODO

Query Parameters

Name	Type	Required	Default	Description
transactionExternalKey	string	yes	none	Transaction external key
withPluginInfo	boolean	no	false	If true, include plugin info
withAttempts	boolean	no	false	If true, include payment attempts

Response

If successful, returns a status code of 200 and a payment object including the specified transaction.

Mark a pending payment transaction as succeeded or failed

Sets the status of a PENDING PaymentTransaction to SUCCESS or PAYMENT_FAILURE

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}

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 '{"paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82", "status": "SUCCESS"}' \
    "http://127.0.0.1:8080/1.0/kb/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("37d15a2f-55ac-40ab-a873-08faae78f213");
PaymentTransaction paymentTransaction = new PaymentTransaction();
paymentTransaction.setStatus(TransactionStatus.SUCCESS);
paymentTransaction.setPaymentId(UUID.fromString("27d15e39-b25c-4dc1-92cf-5487397a48a6");

paymentTransactionApi.notifyStateChanged(paymentTransactionId, 
                                         paymentTransaction, 
                                         null, 
                                         requestOptions);

TODO

TODO

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/payments/27d15e39-b25c-4dc1-92cf-5487397a48a6/
< Content-Type: application/json
< Content-Length: 0

class Payment {
    org.killbill.billing.client.model.gen.Payment@b3bf4de6
    accountId: f7aadaf2-1594-4bd8-b8fd-a09783e04b6d
    paymentId: 27d15e39-b25c-4dc1-92cf-5487397a48a6
    paymentNumber: 43
    paymentExternalKey: 27d15e39-b25c-4dc1-92cf-5487397a48a6
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 10.00
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: 47953e4d-2b52-4ac2-a016-340eb0074444
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@38b46552
        transactionId: 37d15a2f-55ac-40ab-a873-08faae78f213
        transactionExternalKey: 37d15a2f-55ac-40ab-a873-08faae78f213
        paymentId: 27d15e39-b25c-4dc1-92cf-5487397a48a6
        paymentExternalKey: 27d15e39-b25c-4dc1-92cf-5487397a48a6
        transactionType: PURCHASE
        amount: 10.00
        currency: USD
        effectiveDate: 2021-05-07T09:16:52.000Z
        processedAmount: 10.00
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: null
        gatewayErrorMsg: null
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

TODO

TODO

Request Body

A PaymentTransaction object including, at least, a paymentId and a status (SUCCESS or PAYMENT_FAILURE)

Query Parameters

None.

Response

If successful, returns a status code of 201 and the payment object.

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 payment transaction audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified payment. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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/paymentTransactions/07655b3c-7f17-4172-b193-ece48e5741ad/auditLogsWithHistory"

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("41f4d299-4371-4876-96b4-0b3cc81b246b");

List<AuditLog> result = paymentTransactionApi.getTransactionAuditLogsWithHistory(paymentTransactionId, 
                                                                                 requestOptions);

TODO

TODO

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-18T18:58:11.000Z",
    "objectType": "TRANSACTION",
    "objectId": "07655b3c-7f17-4172-b193-ece48e5741ad",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "84ac4088-dc76-4fde-9ff0-63e228b5e6fc",
    "history": {
      "id": null,
      "createdDate": "2018-07-18T18:58:11.000Z",
      "updatedDate": "2018-07-18T18:58:11.000Z",
      "recordId": 63,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "attemptId": null,
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionType": "AUTHORIZE",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "transactionStatus": "UNKNOWN",
      "amount": 0,
      "currency": "USD",
      "processedAmount": null,
      "processedCurrency": null,
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "tableName": "PAYMENT_TRANSACTIONS",
      "historyTableName": "PAYMENT_TRANSACTION_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2018-07-18T18:58:11.000Z",
    "objectType": "TRANSACTION",
    "objectId": "07655b3c-7f17-4172-b193-ece48e5741ad",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "84ac4088-dc76-4fde-9ff0-63e228b5e6fc",
    "history": {
      "id": null,
      "createdDate": "2018-07-18T18:58:11.000Z",
      "updatedDate": "2018-07-18T18:58:11.000Z",
      "recordId": 63,
      "accountRecordId": 120,
      "tenantRecordId": 101,
      "attemptId": null,
      "paymentId": "e8edd4c6-2f85-4375-95f3-e78ca4d85b82",
      "transactionExternalKey": "07655b3c-7f17-4172-b193-ece48e5741ad",
      "transactionType": "AUTHORIZE",
      "effectiveDate": "2018-07-18T18:58:11.000Z",
      "transactionStatus": "SUCCESS",
      "amount": 0,
      "currency": "USD",
      "processedAmount": 0,
      "processedCurrency": "USD",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "tableName": "PAYMENT_TRANSACTIONS",
      "historyTableName": "PAYMENT_TRANSACTION_HISTORY"
    }
  }
]

[class AuditLog {
    changeType: INSERT
    changeDate: 2021-05-05T11:54:19.000Z
    objectType: TRANSACTION
    objectId: 41f4d299-4371-4876-96b4-0b3cc81b246b
    changedBy: Kill Bill Client Tutorial
    reasonCode: Demonstrating Kill Bill Client
    comments: Demonstrating Kill Bill Client
    userToken: d05cc121-5a34-4b9e-b876-c48bab354418
    history: {id=null, createdDate=2021-05-05T11:54:19.000Z, updatedDate=2021-05-05T11:54:19.000Z, recordId=42, accountRecordId=39, tenantRecordId=1, attemptId=null, paymentId=59f1e0cb-58ae-481a-afbb-6709e86066de, transactionExternalKey=41f4d299-4371-4876-96b4-0b3cc81b246b, transactionType=PURCHASE, effectiveDate=2021-05-05T11:54:19.000Z, transactionStatus=UNKNOWN, amount=1.0, currency=USD, processedAmount=null, processedCurrency=null, gatewayErrorCode=null, gatewayErrorMsg=null, tableName=PAYMENT_TRANSACTIONS, historyTableName=PAYMENT_TRANSACTION_HISTORY}
}, class AuditLog {
    changeType: UPDATE
    changeDate: 2021-05-05T11:54:19.000Z
    objectType: TRANSACTION
    objectId: 41f4d299-4371-4876-96b4-0b3cc81b246b
    changedBy: Kill Bill Client Tutorial
    reasonCode: Demonstrating Kill Bill Client
    comments: Demonstrating Kill Bill Client
    userToken: d05cc121-5a34-4b9e-b876-c48bab354418
    history: {id=null, createdDate=2021-05-05T11:54:19.000Z, updatedDate=2021-05-05T11:54:19.000Z, recordId=42, accountRecordId=39, tenantRecordId=1, attemptId=null, paymentId=59f1e0cb-58ae-481a-afbb-6709e86066de, transactionExternalKey=41f4d299-4371-4876-96b4-0b3cc81b246b, transactionType=PURCHASE, effectiveDate=2021-05-05T11:54:19.000Z, transactionStatus=UNKNOWN, amount=1.0, currency=USD, processedAmount=0.0, processedCurrency=USD, gatewayErrorCode=null, gatewayErrorMsg=null, tableName=PAYMENT_TRANSACTIONS, historyTableName=PAYMENT_TRANSACTION_HISTORY}
}]

TODO

TODO

Query Parameters

None.

Response

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

Custom Fields

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

Add custom fields to payment transaction

Adds one or more custom fields to a PaymentTransaction object. Existing custom fields are not modified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

paymentTransactionApi.createTransactionCustomFields(paymentTransactionId, 
                                                    customFields, 
                                                    requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()
body = CustomField(name='Test Custom Field', value='test_value')

paymentTransactionApi.create_transaction_custom_fields(payment_transaction_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/paymentTransactions/41f4d299-4371-4876-96b4-0b3cc81b246b/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: TRANSACTION
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

TODO

no content

Request Body

A JSON string representing the custom field object or objects 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 payment transaction.

Retrieve payment transaction custom fields

Retrieves the custom fields associated with a payment transaction

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/customFields

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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");

List<CustomField> customFields = paymentTransactionApi.getTransactionCustomFields(paymentTransactionId,
                                                                                  AuditLevel.NONE,
                                                                                  requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

paymentTransactionApi.get_transaction_custom_fields(payment_transaction_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "objectType": "TRANSACTION",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: cca08349-8b26-41c7-bfcc-2e3cf70a0f28
    objectType: TRANSACTION
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

TODO

[{'audit_logs': [],
 'custom_field_id': '893e0286-2b48-493b-99af-aac9b172dc75',
 'name': 'Test Custom Field',
 'object_id': '924bebe7-58e7-40e8-a5ed-192efb59d8ee',
 'object_type': 'TRANSACTION',
 'value': 'test_value'}]

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for a payment transaction

Modifies the custom fields associated with a PaymentTransaction object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "customFieldId": "e4bac228-872d-4966-8072-2c3ac06442ed",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/customFields' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
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);
paymentTransactionApi.modifyTransactionCustomFields(paymentTransactionId, 
                                                    customFields, 
                                                    requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
body = CustomField(custom_field_id=custom_field_id, name='Test Modify', value='test_modify_value')

paymentTransactionApi.modify_transaction_custom_fields(payment_transaction_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Requst Body

A JSON string representing a list of custom fields to substitute for the existing ones. For example:

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

Although the field name and object type can be specified in the request body, these cannot be modified, only the field value can be modified.

Query Parameters

None.

Response

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

Remove custom fields from a payment transaction

Removes a specified set of custom fields from a payment transaction object

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=e4bac228-872d-4966-8072-2c3ac06442ed' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("cca08349-8b26-41c7-bfcc-2e3cf70a0f28");
UUID customFieldsId = UUID.fromString("9913e0f6-b5ef-498b-ac47-60e1626eba8f");
List<UUID> customFieldsList = ImmutableList.<UUID>of(customFieldsId);
paymentTransactionApi.deleteTransactionCustomFields(paymentTransactionId, 
                                                    customFieldsList, 
                                                    requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'

paymentTransactionApi.delete_transaction_custom_fields(payment_transaction_id,
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	none	Comma separated list of custom field object IDs that should be deleted.

Response

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

Tags

See Account Tags for an introduction.

The are no system tags applicable to a Payment Transaction.

Add tags to a payment transaction

Adds one or more tags to a PaymentTransaction object. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

UUID paymentTransactionId = UUID.fromString("917992d3-5f1f-4828-9fff-799cc4211aa9");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

Tags result = paymentTransactionApi.createTransactionTags(paymentTransactionId, 
                                                          ImmutableList.<UUID>of(tagDefinitionId), 
                                                          requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

paymentTransactionApi.create_transaction_tags(payment_transaction_id,
                                              tag,
                                              created_by,
                                              api_key,
                                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: TRANSACTION
    objectId: 917992d3-5f1f-4828-9fff-799cc4211aa9
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: AUTO_PAY_OFF
    auditLogs: []
}

TODO

no content

Request Body

Provides a list of tag definition Ids in JSON format

Query Parameters

None.

Response

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

Retrieve payment transaction tags

Retrieves all tags attached to this payment transaction.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/tags

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/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags' 

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

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

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = paymentTransactionApi.getTransactionTags(paymentTransactionId, 
                                                          includedDeleted, 
                                                          AuditLevel.FULL, 
                                                          requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = '28af3cb9-275b-4ac4-a55d-a0536e479069'

paymentTransactionApi.get_transaction_tags(payment_transaction_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "tagId": "890e3b13-3114-478b-9365-50f1a2682143",
    "objectType": "TRANSACTION",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "tagDefinitionId": "353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName": "foo",
    "auditLogs": []
  }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: TRANSACTION
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

TODO

[{'audit_logs': [],
 'object_id': '41b6b214-c3f7-40ea-89cd-6a4ecbd9083b',
 'object_type': 'TRANSACTION',
 'tag_definition_id': '353752dd-9041-4450-b782-a8bb03a923c8',
 'tag_definition_name': 'foo',
 'tag_id': '865e0c77-def7-4880-ac80-11c21a5e571d'}]

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted tags
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from a payment transaction

Removes a list of tags attached to a payment transaction.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/paymentTransactions/{transactionId}/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' \
    'http://127.0.0.1:8080/1.0/kb/paymentTransactions/8fe697d4-2c25-482c-aa45-f6cd5a48186d/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'    

import org.killbill.billing.client.api.gen.PaymentTransactionApi;
protected PaymentTransactionApi paymentTransactionApi;

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

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

paymentTransactionApi.deleteTransactionTags(paymentTransactionId, 
                                            ImmutableList.<UUID>of(tagDefinitionId), 
                                            requestOptions);

TODO

paymentTransactionApi = killbill.api.PaymentTransactionApi()

payment_transaction_id = 'dce5b2a0-0f0f-430b-9427-545ba4be5c7f'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"] 

paymentTransactionApi.delete_transaction_tags(payment_transaction_id,
                                              created_by,
                                              api_key,
                                              api_secret,
                                              tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

TODO

no content

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of string	yes	none	List of tag definition IDs identifying the tags that should be removed.

Response

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

Invoice Payment

An InvoicePayment is a Payment that is made against a specific invoice.

By default the system will always attempt to make a full payment against an invoice, but Kill Bill also allows multiple partial payments. Partial payments can be made against unpaid - or partially paid - invoices by triggerring a payment against the Invoice resource. The reverse is not true; a single payment across multiple invoices is not (yet) supported.

See Payment for further information.

Invoice Payment Resource

The InvoicePayment resource represents a payment associated with a given invoice. It is identical to the Payment resource except for the inclusion of the targetInvoiceId attribute.

Name	Type	Generated by	Description
targetInvoiceId	string	system	UUID for the invoice to be paid
accountId	string	system	UUID for the account to be paid
paymentId	string	system	UUID for the payment
paymentNumber	number	user	User's ID number for the payment
paymentExternalKey	string	user	optional external key
authAmonunt	number	user or system	Total authorized amount (see below)
capturedAmonunt	number	user or system	Total captured amount (see below)
purchasedAmonunt	number	user or system	Total purchased amount (see below)
refundedAmount	number	user or system	Total refunded amount (see below)
creditedAmount	number	user or system	Total credited amount (see below)
currency	string	user	currency to be used
paymentMethod	string	system	UUID for the payment method used
transactions	list	system	list of paymentTransactions, if any (see below)
paymentAttempts	list	system	list of paymentAttempts, if any (see below)

• authAmount, capturedAmount, purchasedAmount, refundedAmount, creditedAmount: These are total amounts across all transactions associated with this Payment.

• creditedAmount: this credit represents the actual money sent back by the merchant to the user, which is extremely rare. It is unrelated to the associated invoice or account credits.

• *paymentTransactions *: List of transactions for this Payment. The attributes for a PaymentTransaction are described here.

• paymentAttempts: Only applicable when the system is configured to retry failed attempts.

Invoice Payment Transaction Resource

The InvoicePaymentTransaction resource represents a payment transaction associated with a given InvoicePayment. It is identical to the PaymentTransaction resource except for the inclusion of the isAdjusted and adjustments attributes. The attributes for this resource object are:

Name	Type	Generated by	Description
transactionId	string	system	UUID for the transaction
transactionExternalKey	string	user or system	Optional external key
paymentId	string	system	UUID for the transaction
paymentExternalKey	string	user or system	Optional external key
transactionType	string	user	Transaction type (see below)
amount	number	system	Total amount of the transaction
currency	string	user or system	Currency associated with the account
effectiveDate	string	user	Effective date of the transaction
processedAmount	number	system	The amount processed by the gateway (see below)
processedCurrency	string	system	The currency processed by the gateay (see below)
status	string	system	Transaction status (see below)
gatewayErrorCode	string	system	Error code returned by the payment gateway
gatewayErrorMsg	string	system	Error message returned by the payment gateway
firstPaymentReferenceId	string	system	Payment gateway reference
secondPaymentReferenceId	string	system	see below
properties	string	user	see below
isAdjusted	boolean	system	true if this object includes one or more InvoiceItem adjustments
adjustments	list	system	List of adjusted InvoiceItem resources showing adjusted amounts

• transactionType: Possible values are: AUTHORIZE, CAPTURE, CHARGEBACK, CREDIT, PURCHASE, REFUND, VOID

• processedAmount: This will often match amount, but could be different, perhaps due to currency conversion

• processedCurrency: This will often match currency, but could be different, perhaps due to currency conversion

• status: Possible values are: SUCCESS, UNKNOWN, PENDING, PAYMENT_FAILURE, PLUGIN_FAILURE, or PAYMENT_SYSTEM_OFF

• secondPaymentReferenceId: Typically the ID from the actual payment processor, when the gateway is a PSP

• properties: Plugin-specific properties to be interpreted by the plugin

Invoice Payment

These endpoints initiate transactions on an existing InvoicePayment. Many other applicable transactions are given in the Payment section. To begin a new Payment, see Trigger a Payment in the Account API.

Retrieve a payment by id

Retrieves an invoice payment by its payment Id, which is given as a path parameter

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}

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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("80f5bfca-e142-4320-b8f2-ae4530ca7172");
Boolean withPluginInfo = false; // Will not reflect plugin info
Boolean withAttempts = false; // Will not reflect payment attempts
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

InvoicePayment invoicePayment = invoicePaymentApi.getInvoicePayment(paymentId, 
                                                                    withPluginInfo,
                                                                    withAttempts,
                                                                    NULL_PLUGIN_PROPERTIES,
                                                                    AuditLevel.NONE,
                                                                    requestOptions);

payment_id = '28aef37a-7655-4351-985a-02b961ae4ac7'
with_plugin_info = false
with_attempts = false

KillBillClient::Model::InvoicePayment.find_by_id(payment_id, 
                                                 with_plugin_info, 
                                                 with_attempts, 
                                                 @options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '5e9d8b82-2664-4a36-85a1-37471a0b618a'

invoicePaymentApi.get_invoice_payment(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
{
  "targetInvoiceId": "4be34fe4-5845-4a35-afd8-632ad04cccf9",
  "accountId": "8b66b9f9-bfb4-463a-86c7-e267128a294a",
  "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
  "paymentNumber": "19",
  "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
  "authAmount": 0,
  "capturedAmount": 0,
  "purchasedAmount": 500,
  "refundedAmount": 0,
  "creditedAmount": 0,
  "currency": "USD",
  "paymentMethodId": "39f3461c-5357-42f7-a8a9-ec79502fdb6b",
  "transactions": [
    {
      "transactionId": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "transactionExternalKey": "6787dc2d-4f5e-49b5-9764-0070fd1238c2",
      "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
      "paymentExternalKey": "cc7fcd4d-e701-4679-9741-41289103db83",
      "transactionType": "PURCHASE",
      "amount": 500,
      "currency": "USD",
      "effectiveDate": "2018-07-19T20:48:34.000Z",
      "processedAmount": 500,
      "processedCurrency": "USD",
      "status": "SUCCESS",
      "gatewayErrorCode": null,
      "gatewayErrorMsg": null,
      "firstPaymentReferenceId": null,
      "secondPaymentReferenceId": null,
      "properties": null,
      "auditLogs": []
    }
  ],
  "paymentAttempts": null,
  "auditLogs": []
}

class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@47ec807
    targetInvoiceId: 8ff7ded6-e524-4f38-94f7-d9aacef8b88b
    accountId: ed1029e6-dcc0-4b1e-ae94-e00fb14efd41
    paymentId: 80f5bfca-e142-4320-b8f2-ae4530ca7172
    paymentNumber: 1
    paymentExternalKey: 80f5bfca-e142-4320-b8f2-ae4530ca7172
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 249.95
    refundedAmount: 249.95
    creditedAmount: 0
    currency: USD
    paymentMethodId: 083cc55b-65e9-484c-9c33-0d6956540a0e
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@a0308e7f
        transactionId: b9a795f0-c9d0-4e89-a0b2-783d8844bb44
        transactionExternalKey: b9a795f0-c9d0-4e89-a0b2-783d8844bb44
        paymentId: 80f5bfca-e142-4320-b8f2-ae4530ca7172
        paymentExternalKey: 80f5bfca-e142-4320-b8f2-ae4530ca7172
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-05-27T00:03:46.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@c4c601f0
        transactionId: 5c59f93d-7f6d-406b-b499-7a1547c00c9f
        transactionExternalKey: f4e8c3dc-9e97-4000-b82c-1f0dcd1cf84e
        paymentId: 80f5bfca-e142-4320-b8f2-ae4530ca7172
        paymentExternalKey: 80f5bfca-e142-4320-b8f2-ae4530ca7172
        transactionType: REFUND
        amount: 249.95
        currency: USD
        effectiveDate: 2012-05-27T00:03:47.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "targetInvoiceId":"375f1ade-b4eb-4344-bb64-e44fe7a5dea1",
   "accountId":"db0d9182-c7cf-4bb7-aa3e-73a9f7105606",
   "paymentId":"28aef37a-7655-4351-985a-02b961ae4ac7",
   "paymentNumber":"595",
   "paymentExternalKey":"28aef37a-7655-4351-985a-02b961ae4ac7",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"0e47ceb2-8cfc-4005-86ac-5fe88ecce8ce",
   "transactions":[
      {
         "transactionId":"37c0189d-737c-435c-bfbd-944aabe27d1b",
         "transactionExternalKey":"37c0189d-737c-435c-bfbd-944aabe27d1b",
         "paymentId":"28aef37a-7655-4351-985a-02b961ae4ac7",
         "paymentExternalKey":"28aef37a-7655-4351-985a-02b961ae4ac7",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

{'account_id': '8a758318-25fb-46e1-a385-a8f8354ec903',
 'audit_logs': [],
 'auth_amount': 0.0,
 'captured_amount': 0.0,
 'credited_amount': 0.0,
 'currency': 'USD',
 'payment_attempts': None,
 'payment_external_key': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
 'payment_id': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
 'payment_method_id': 'eb737a51-d230-46fe-ad95-8ddf0b8effe3',
 'payment_number': '337',
 'purchased_amount': 50.0,
 'refunded_amount': 0.0,
 'target_invoice_id': '8291871e-b16e-45e6-a971-577d44727327',
 'transactions': [{'amount': 50.0,
                   'audit_logs': [],
                   'currency': 'USD',
                   'effective_date': datetime.datetime(2018, 5, 9, 14, 27, 9, tzinfo=tzutc()),
                   'first_payment_reference_id': None,
                   'gateway_error_code': None,
                   'gateway_error_msg': None,
                   'payment_external_key': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
                   'payment_id': '5e9d8b82-2664-4a36-85a1-37471a0b618a',
                   'processed_amount': 50.0,
                   'processed_currency': 'USD',
                   'properties': None,
                   'second_payment_reference_id': None,
                   'status': 'SUCCESS',
                   'transaction_external_key': '70a36a47-878e-4fd8-8401-1ab2f4403d41',
                   'transaction_id': '70a36a47-878e-4fd8-8401-1ab2f4403d41',
                   'transaction_type': 'PURCHASE'}]}

Query Parameters

Name	Type	Required	Default	Description
withPluginInfo	boolean	no	false	if true, include plugin info
withAttempts	boolean	no	false	if true, include payment attempts

Returns

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

Refund a payment, and adjust the invoice if needed

Refunds a payment, and optionally adds the amount to one or more invoice items

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/refunds

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "amount": 50,
          "isAdjusted": false
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/refunds' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("45d6f4c5-21be-49b1-99c5-7b0c3c985bf0");

InvoicePaymentTransaction refund = new InvoicePaymentTransaction();
refund.setPaymentId(paymentId);
refund.setAmount(BigDecimal.ONE);

UUID paymentMethodId = UUID.fromString("28a3ed1a-7a58-4ac2-b864-2ca723abb864");

ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

invoicePaymentApi.createRefundWithAdjustments(paymentId, 
                                              refund, 
                                              paymentMethodId, 
                                              NULL_PLUGIN_PROPERTIES, 
                                              requestOptions);

payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
amount ='50.0'
adjustments = nil
KillBillClient::Model::InvoicePayment.refund(payment_id, 
                                             amount, 
                                             adjustments, 
                                             user, 
                                             reason, 
                                             comment, 
                                             options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
body = PaymentTransaction(amount=50.0)

invoicePaymentApi.create_refund_with_adjustments(payment_id,
                                                 body,
                                                 created_by,
                                                 api_key,
                                                 api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/
< Content-Type: application/json
< Content-Length: 0

class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@916e89e1
    targetInvoiceId: 5de44543-2cd9-4781-b6a3-12c47a9244ed
    accountId: 9b535e8a-dbfe-479a-8936-75c8b5e9cf45
    paymentId: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
    paymentNumber: 1
    paymentExternalKey: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 249.95
    refundedAmount: 1
    creditedAmount: 0
    currency: USD
    paymentMethodId: 28a3ed1a-7a58-4ac2-b864-2ca723abb864
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@ab430f5e
        transactionId: 6727a8db-ec00-4d85-89f2-cda778b21ddf
        transactionExternalKey: 6727a8db-ec00-4d85-89f2-cda778b21ddf
        paymentId: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
        paymentExternalKey: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:05.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }, class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@d404a66c
        transactionId: a29e0204-a4db-400f-9f5f-3de1e57169d8
        transactionExternalKey: b4903f2e-ea23-4c95-a2c8-a3d81b7dfd60
        paymentId: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
        paymentExternalKey: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
        transactionType: REFUND
        amount: 1
        currency: USD
        effectiveDate: 2012-09-26T00:00:10.000Z
        processedAmount: 1
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "targetInvoiceId":"045900ff-5b2a-4709-b7bd-d70501998dd5",
   "accountId":"dc7d2b03-d989-4cfa-96db-f02b6475950e",
   "paymentId":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
   "paymentNumber":"347",
   "paymentExternalKey":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":20.0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"4103cf10-08b4-4685-b3c2-1c2c88b0f32f",
   "transactions":[
      {
         "transactionId":"1cd767ed-b3c1-4369-a447-09308f3bebf4",
         "transactionExternalKey":"1cd767ed-b3c1-4369-a447-09308f3bebf4",
         "paymentId":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
         "paymentExternalKey":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"69f72535-dd5d-4784-b0a6-05d6f64359cf",
         "transactionExternalKey":"d7118799-0268-45c9-a0e0-455fa2731a8b",
         "paymentId":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
         "paymentExternalKey":"8d85a8e8-c94b-438f-aac1-e8cb436b2c05",
         "transactionType":"REFUND",
         "amount":20.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":20.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

Name	Type	Required	Default	Description
externalPayment	boolean	no	false	choose true if the payment method is external
paymentMethodId	string	yes	none	paymentMethod id

Response

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

Record a chargeback

Creates a CHARGEBACK InvoicePaymentTransaction for a specified InvoicePayment. The InvoicePayment is identified by its paymentId given as a path parameter. The captured amount is reduced by the chargeback amount. If appropriate this amount will be added back to one or more invoice items.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/chargebacks

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "amount": 5,
          "isAdjusted": false
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/chargebacks' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("96930ff3-82e1-4556-888a-0cb07ec120d6");

InvoicePaymentTransaction body = new InvoicePaymentTransaction();
body.setPaymentId(paymentId);
body.setAmount(new BigDecimal("50.00"));

InvoicePayment result = invoicePaymentApi.createChargeback(paymentId, 
                                                           body, 
                                                           requestOptions);

payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'
amount = '50.0'
currency = 'USD'
effective_date = "2013-08-01"

KillBillClient::Model::InvoicePayment.chargeback(payment_id, 
                                                 amount,
                                                 currency,
                                                 effective_date,
                                                 user, 
                                                 reason,
                                                 comment, 
                                                 options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'
body = PaymentTransaction(amount=50.0, currency='USD')

invoicePaymentApi.create_chargeback(payment_id, 
                                    body, 
                                    created_by, 
                                    api_key, 
                                    api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/
< Content-Type: application/json
< Content-Length: 0

class InvoicePayment {
    org.killbill.billing.client.model.gen.InvoicePayment@e920eb58
    targetInvoiceId: 84ae9d9a-badf-45c2-b53b-7b8a077e42ea
    accountId: 4dd59373-be7a-409e-beaa-a17e8b234591
    paymentId: 96930ff3-82e1-4556-888a-0cb07ec120d6
    paymentNumber: 1
    paymentExternalKey: 96930ff3-82e1-4556-888a-0cb07ec120d6
    authAmount: 0
    capturedAmount: 0
    purchasedAmount: 0.00
    refundedAmount: 0
    creditedAmount: 0
    currency: USD
    paymentMethodId: a9408abd-d505-4462-afe6-0d29a202d8b3
    transactions: [class PaymentTransaction {
        org.killbill.billing.client.model.gen.PaymentTransaction@e72668f3
        transactionId: 583ba30d-c6f4-4600-934e-73ef9782e444
        transactionExternalKey: 583ba30d-c6f4-4600-934e-73ef9782e444
        paymentId: 96930ff3-82e1-4556-888a-0cb07ec120d6
        paymentExternalKey: 96930ff3-82e1-4556-888a-0cb07ec120d6
        transactionType: PURCHASE
        amount: 249.95
        currency: USD
        effectiveDate: 2012-09-26T00:00:08.000Z
        processedAmount: 249.95
        processedCurrency: USD
        status: SUCCESS
        gatewayErrorCode: 
        gatewayErrorMsg: 
        firstPaymentReferenceId: null
        secondPaymentReferenceId: null
        properties: null
        auditLogs: []
    }]
    paymentAttempts: null
    auditLogs: []
}

{
   "targetInvoiceId":"dd185d1c-a4c5-4420-b06a-df42af446975",
   "accountId":"bb43a670-c644-4121-a981-ba5f5dac3b94",
   "paymentId":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
   "paymentNumber":"339",
   "paymentExternalKey":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":0.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"a9e97ad3-ef17-4475-8464-25d09e3b5290",
   "transactions":[
      {
         "transactionId":"49eff7ec-2982-428a-b4f0-ed99dcbfbb82",
         "transactionExternalKey":"49eff7ec-2982-428a-b4f0-ed99dcbfbb82",
         "paymentId":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
         "paymentExternalKey":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"16d55de4-5dd8-4306-87c3-d05db796d90f",
         "transactionExternalKey":"d18943b1-96b7-49fd-9f11-78d55f361b18",
         "paymentId":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
         "paymentExternalKey":"2276b3c9-4e51-41b2-b5bf-9ddc11582ee4",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:03.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

None.

Response

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

Record a chargeback reversal

Reverses a CHARGEBACK InvoicePaymentTransaction, if permitted by the Payment plugin. The chargeback amount is added back to the captured amount. The payment is identified by its paymentId which is given as a path parameter.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/chargebackReversals

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 'X-Killbill-CreatedBy: demo' \
    -d '{
          "transactionExternalKey": "a335f7d2-e115-436f-8c63-2b0114d974de",
          "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83",
          "effectiveDate": "2018-07-20T15:05:36.853Z"        
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/chargebackReversals' 

TODO

payment_id = '7a5d4997-5d44-4a82-8371-a410ea5615f4'
chargeback_transaction_external_key = '99c45d07-abe4-4bc7-a207-0524548c1b08'
effective_date = "2013-08-01"

KillBillClient::Model::InvoicePayment.chargeback_reversal(payment_id,
                                                          chargeback_transaction_external_key, 
                                                          effective_date, 
                                                          user, 
                                                          reason, 
                                                          comment, 
                                                          options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '7a5d4997-5d44-4a82-8371-a410ea5615f4'
transaction_external_key = '99c45d07-abe4-4bc7-a207-0524548c1b08'
body = PaymentTransaction(amount=50.0, 
                          currency='USD', 
                          transaction_external_key=transaction_external_key)

invoicePaymentApi.create_chargeback_reversal(payment_id, 
                                             body, 
                                             created_by, 
                                             api_key, 
                                             api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/
< Content-Type: application/json
< Content-Length: 0

{
   "targetInvoiceId":"dee84f4e-5781-442c-845e-423a6bcb6b2b",
   "accountId":"93182158-c000-4c8d-893e-1e758e975a2a",
   "paymentId":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
   "paymentNumber":"338",
   "paymentExternalKey":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
   "authAmount":0,
   "capturedAmount":0,
   "purchasedAmount":50.0,
   "refundedAmount":0,
   "creditedAmount":0,
   "currency":"USD",
   "paymentMethodId":"5d32f8f4-24b1-4519-85e4-356b5c087f76",
   "transactions":[
      {
         "transactionId":"ef824f7f-30f6-4b08-82d4-5add7e7a773f",
         "transactionExternalKey":"ef824f7f-30f6-4b08-82d4-5add7e7a773f",
         "paymentId":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "paymentExternalKey":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "transactionType":"PURCHASE",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:02.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"90fef451-10d6-4ebd-a126-43c3ab4315c2",
         "transactionExternalKey":"99c45d07-abe4-4bc7-a207-0524548c1b08",
         "paymentId":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "paymentExternalKey":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "transactionType":"CHARGEBACK",
         "amount":50.0,
         "currency":"USD",
         "effectiveDate":"2013-08-01T06:00:04.000Z",
         "processedAmount":50.0,
         "processedCurrency":"USD",
         "status":"SUCCESS",
         "auditLogs":[]
      },
      {
         "transactionId":"a1c3648c-f3c0-4c0f-9eb0-e56c7ab9c798",
         "transactionExternalKey":"99c45d07-abe4-4bc7-a207-0524548c1b08",
         "paymentId":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "paymentExternalKey":"7a5d4997-5d44-4a82-8371-a410ea5615f4",
         "transactionType":"CHARGEBACK",
         "effectiveDate":"2013-08-01T06:00:05.000Z",
         "processedAmount":0.0,
         "status":"PAYMENT_FAILURE",
         "auditLogs":[]
      }
   ],
   "auditLogs":[]
}

no content

Request Body

An InvoicePaymentTransaction object, including at least the amount attribute and the isAdjusted attribute. If isAdjusted is true, then the object must also include the attribute adjustments which is a list of InvoiceItem objects giving the invoiceItemId, the invoiceId, and the adjusted amount for each of the adjustments to be made.

Query Parameters

None.

Response

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

Complete an existing transaction

Completes any existing InvoicePaymentTransaction that is in a PENDING state, based on its paymentId given as a path parameter.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'Content-Type: application/json' \
    -H 'X-Killbill-CreatedBy: demo' \
    -d '{
            "paymentId": "cc7fcd4d-e701-4679-9741-41289103db83"
        }' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("80f5bfca-e142-4320-b8f2-ae4530ca7172");
PaymentTransaction body = new PaymentTransaction();
ImmutableList<String> NULL_PLUGIN_NAMES = null;
ImmutableMap<String, String> NULL_PLUGIN_PROPERTIES = null;

invoicePaymentApi.completeInvoicePaymentTransaction(paymentId, 
                                                    body, 
                                                    NULL_PLUGIN_NAMES, 
                                                    NULL_PLUGIN_PROPERTIES, 
                                                    requestOptions);

payment_id = '2276b3c9-4e51-41b2-b5bf-9ddc11582ee4'

KillBillClient::Model::InvoicePayment.complete_invoice_payment_transaction(payment_id, 
                                                                           user, 
                                                                           reason, 
                                                                           comment, 
                                                                           options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
body = PaymentTransaction(payment_id=payment_id)

invoicePaymentApi.complete_invoice_payment_transaction(payment_id, 
                                                       body, 
                                                       created_by, 
                                                       api_key, 
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

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 InvoicePayment objects. For details on Custom Fields see Custom Field.

Add custom fields to invoice payment

Adds one or more custom fields to an InvoicePayment object. Existing custom fields are not modified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "name": "Test Custom Fields",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("59860a0d-c032-456d-a35e-3a48fe8579e5");
final ImmutableList<AuditLog> EMPTY_AUDIT_LOGS = ImmutableList.<AuditLog>of();

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

invoicePaymentApi.createInvoicePaymentCustomFields(paymentId, 
                                                   customFields, 
                                                   requestOptions);

custom_field = KillBillClient::Model::CustomFieldAttributes.new
custom_field.object_type = 'INVOICE_PAYMENT'
custom_field.name = 'Test Custom Field'
custom_field.value = 'test_value'

invoice_payment.add_custom_field(custom_field, 
                                 user,
                                 reason,
                                 comment,
                                 options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
body = CustomField(name='Test Custom Field', value='test_value')

invoicePaymentApi.create_invoice_payment_custom_fields(payment_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: INVOICE_PAYMENT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"INVOICE_PAYMENT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

no content

Request Body

A JSON string representing the custom field object or objects to be added.

Query Parameters

None.

Response

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

Retrieve invoice payment custom fields

Retrieves the custom fields associated with an InvoicePayment object

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/customFields

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/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

List<CustomField> customFields = invoicePaymentApi.getInvoicePaymentCustomFields(paymentId,
                                                                                 AuditLevel.NONE,
                                                                                 requestOptions);

audit = 'NONE'

invoice_payment.custom_fields(audit, options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'

invoicePaymentApi.get_invoice_payment_custom_fields(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "customFieldId": "3fbf75aa-6f22-4a02-974b-55eeded2cf6b",
    "objectId": "2495e35e-2b96-434c-8877-62dbbf20f7e9",
    "objectType": "PAYMENT",
    "name": "Test Custom Field",
    "value": "test_value",
    "auditLogs": []
  }
]

//First element of the list
class CustomField {
    org.killbill.billing.client.model.gen.CustomField@c7d0c38a
    customFieldId: null
    objectId: 59860a0d-c032-456d-a35e-3a48fe8579e5
    objectType: INVOICE_PAYMENT
    name: Test Custom Field
    value: test_value
    auditLogs: []
}

[
   {
      "customFieldId":"7fb3dde7-0911-4477-99e3-69d142509bb9",
      "objectId":"4927c1a2-3959-4f71-98e7-ce3ba19c92ac",
      "objectType":"INVOICE_PAYMENT",
      "name":"Test Custom Field",
      "value":"test_value",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'custom_field_id': '9913e0f6-b5ef-498b-ac47-60e1626eba8f',
 'name': 'Test Custom Field',
 'object_id': 'f33e0adc-78df-438a-b920-aaacd7f8597a',
 'object_type': 'PAYMENT',
 'value': 'test_value'}]

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Modify custom fields for an invoice payment

Modifies the custom fields associated with an InvoicePayment object

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[{ 
            "customFieldId": "e2408cac-931b-43eb-855b-9f2902615c39",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = 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");

invoicePaymentApi.modifyInvoicePaymentCustomFields(paymentId, 
                                                   customFieldModified, 
                                                   requestOptions);

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

invoice_payment.modify_custom_field(custom_field,                                                                                            
                                    user, 
                                    reason,
                                    comment, 
                                    options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
body = CustomField(custom_field_id=custom_field_id, name='Test Modify', value='test_modify_value')

invoicePaymentApi.modify_invoice_payment_custom_fields(payment_id,
                                                       [body],
                                                       created_by,
                                                       api_key,
                                                       api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Requst Body

A JSON string representing a list of custom fields to substitute for the existing ones.

Query Parameters

None.

Response

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

Remove custom fields from an invoice payment

Removes a specified set of custom fields from an InvoicePayment object

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/customFields

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H 'X-Killbill-ApiKey: bob' \
    -H 'X-Killbill-ApiSecret: lazar' \
    -H 'X-Killbill-CreatedBy: demo' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/2495e35e-2b96-434c-8877-62dbbf20f7e9/customFields?customField=e2408cac-931b-43eb-855b-9f2902615c39' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

invoicePaymentApi.deleteInvoicePaymentCustomFields(paymentId, 
                                                   customFieldsId, 
                                                   requestOptions);

custom_field_id = custom_field.id

invoice_payment.remove_custom_field(custom_field_id,                                                                                            
                                    user, 
                                    reason,
                                    comment, 
                                    options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = 'f33e0adc-78df-438a-b920-aaacd7f8597a'
custom_field_id = '9913e0f6-b5ef-498b-ac47-60e1626eba8f'
custom_field = [custom_field_id]
invoicePaymentApi.delete_invoice_payment_custom_fields(payment_id,
                                                       created_by,
                                                       api_key,
                                                       api_secret,
                                                       custom_field=custom_field)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
customField	string	yes	none	Comma separated list of custom field object IDs that should be deleted.

Response

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

Tags

See Account Tags for an introduction.

The are no system tags applicable to an InvoicePayment.

Add tags to an invoice payment

Adds one or more tags to an invoice payment object. The tag definitions must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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 'X-Killbill-CreatedBy: demo' \
    -d '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

UUID paymentId = UUID.fromString("45d6f4c5-21be-49b1-99c5-7b0c3c985bf0");

UUID tagDefinitionId = UUID.fromString("353752dd-9041-4450-b782-a8bb03a923c8");

Tags result = invoicePaymentApi.createInvoicePaymentTags(paymentId, 
                                                         ImmutableList.<UUID>of(tagDefinitionId), 
                                                         requestOptions);

tag_name = 'foo'

invoice_payment.add_tag(tag_name,
                        user,
                        reason,
                        comment,
                        options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
tag = ["353752dd-9041-4450-b782-a8bb03a923c8"]

invoicePaymentApi.create_invoice_payment_tags(payment_id,
                                              tag,
                                              created_by,
                                              api_key,
                                              api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 Created
< Location: http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags
< Content-Type: application/json
< Content-Length: 0

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@bd138472
    tagId: 1bb4b638-3886-4f73-90a5-89eb6d1bcf7f
    objectType: INVOICE_PAYMENT
    objectId: 45d6f4c5-21be-49b1-99c5-7b0c3c985bf0
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: []
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"INVOICE_PAYMENT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

no content

Request Body

Provides a list of tag definition Ids in JSON format

Query Parameters

None.

Response

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

Retrieve invoice payment tags

Retrieves all tags attached to this InvoicePayment.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/tags

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/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags' 

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

Boolean includedDeleted = false; // Will not include deleted tags

List<Tag> tags = invoicePaymentApi.getInvoicePaymentTags(paymentId, 
                                                         includedDeleted, 
                                                         AuditLevel.FULL, 
                                                         requestOptions);

included_deleted = false
audit = 'NONE'

invoice_payment.tags(included_deleted,
                     audit,
                     options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '2a1ffd2c-0de1-4f5c-b2a9-27d8deebe596'

invoicePaymentApi.get_invoice_payment_tags(payment_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "tagId": "e7f68cab-3b9a-4150-909a-5f1c17f1fb2b",
    "objectType": "PAYMENT",
    "objectId": "cc7fcd4d-e701-4679-9741-41289103db83",
    "tagDefinitionId": "353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName": "foo",
    "auditLogs": []
  }
]

//First element of the list
class Tag {
    org.killbill.billing.client.model.gen.Tag@cae768d7
    tagId: d724f79d-fad1-4758-b35e-d62708450d90
    objectType: INVOICE_PAYMENT
    objectId: e659f0f3-745c-46d5-953c-28fe9282fc7d
    tagDefinitionId: 353752dd-9041-4450-b782-a8bb03a923c8
    tagDefinitionName: foo
    auditLogs: [class AuditLog {
        changeType: INSERT
        changeDate: 2012-08-25T00:00:02.000Z
        objectType: TAG
        objectId: d724f79d-fad1-4758-b35e-d62708450d90
        changedBy: Toto
        reasonCode: i am god
        comments: no comment
        userToken: e36f7ba5-fb5b-41c0-b47c-77c48ab37dd9
        history: null
    }]
}

[
   {
      "tagId":"a46cfeb6-e175-42db-be62-7f117326ab4e",
      "objectType":"INVOICE_PAYMENT",
      "objectId":"28af3cb9-275b-4ac4-a55d-a0536e479069",
      "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
      "tagDefinitionName":"foo",
      "auditLogs":[]
   }
]

[{'audit_logs': [],
 'object_id': '2a1ffd2c-0de1-4f5c-b2a9-27d8deebe596',
 'object_type': 'PAYMENT',
 'tag_definition_id': '353752dd-9041-4450-b782-a8bb03a923c8',
 'tag_definition_name': 'foo',
 'tag_id': '864ee6aa-1439-4037-8f65-aa114739f09f'}]

Query Parameters

Name	Type	Required	Default	Description
includedDeleted	boolean	no	false	If true, include deleted tags
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Remove tags from an invoice payment

Removes a list of tags attached to an InvoicePayment.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/invoicePayments/{paymentId}/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' \
    'http://127.0.0.1:8080/1.0/kb/invoicePayments/cc7fcd4d-e701-4679-9741-41289103db83/tags?tagDef=00000000-0000-0000-0000-000000000001'    

import org.killbill.billing.client.api.gen.InvoicePaymentApi;
protected InvoicePaymentApi invoicePaymentApi;

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

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

invoicePaymentApi.deleteInvoicePaymentTags(paymentId, 
                                           ImmutableList.<UUID>of(autoPayOffId), 
                                           requestOptions);

tag_name = 'TEST'

invoice_payment.remove_tag(tag_name,
                           user,
                           reason,
                           comment,
                           options)

invoicePaymentApi = killbill.api.InvoicePaymentApi()
payment_id = '8d85a8e8-c94b-438f-aac1-e8cb436b2c05'
tag = ["00000000-0000-0000-0000-000000000002"]

invoicePaymentApi.delete_invoice_payment_tags(payment_id, 
                                              created_by, 
                                              api_key, 
                                              api_secret, 
                                              tag_def=tag)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
tagDef	array of string	yes	none	List of tag definition IDs identifying the tags that should be removed.

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 invoice payment audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified invoice payment. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/payments/{paymentId}/auditLogsWithHistory

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/invoicePayments/8fe697d4-2c25-482c-aa45-f6cd5a48186d/auditLogsWithHistory' 

                                                                                      requestOptions);

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
<
[
  {
    "changeType": "INSERT",
    "changeDate": "2018-07-19T16:39:00.000Z",
    "objectType": "PAYMENT",
    "objectId": "8fe697d4-2c25-482c-aa45-f6cd5a48186d",
    "changedBy": "demo",
    "reasonCode": null,
    "comments": null,
    "userToken": "5d32d0ab-3c08-47b2-8c6d-bb9d2a7fd62c",
    "history": 
    {
      "id": null,
      "createdDate": "2018-07-19T16:39:00.000Z",
      "updatedDate": "2018-07-19T16:39:00.000Z",
      "recordId": 14,
      "accountRecordId": 35,
      "tenantRecordId": 1,
      "accountId": "84c7e0d4-a5ed-405f-a655-3ed16ae19997",
      "paymentNumber": null,
      "paymentMethodId": "916619a4-02bb-4d3d-b3da-2584ac897b19",
      "externalKey": "paymentExternalKey",
      "stateName": null,
      "lastSuccessStateName": null,
      "tableName": "PAYMENTS",
      "historyTableName": "PAYMENT_HISTORY"
    }
  },
]

Query Parameters

None.

Response

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

Usage

When invoicing usage-based subscriptions, you need to record usage data into Kill Bill. Note that Kill Bill is not designed to be a metering system, so it shouldn't contain all data points. Instead, it expects that you record a usage summary on a daily basis (1 API call per subscription per day). For a telco company, for instance, instead of recording all phone calls, you should only record the number of minutes effectively used for each day.

For more information, see our catalog usage documentation and our invoice usage documentation.

Usage Resource

There are several resource objects associated with usage in Kill-Bill. These are shown below.

SubscriptionUsageRecord, along with its components UnitUsageRecord and UsageRecord, is used to enter the daily usage summary into the system.

SubscriptionUsageRecord:

Name	Type	Generated by	Description
subscriptionId	string	system	UUID for the subscription
trackingId	string	user	User's tracking Id for this usage record
unitUsageRecords	list	user	List of UnitUsageRecord (see next)

UnitUsageRecord:

Name	Type	Generated by	Description
unitType	string	user	Type of unit represented
usageRecords	list	user	List of UsageRecord for this unit (see next)

UsageRecord:

Name	Type	Generated by	Description
recordDate	string	user	Date for this record
*amount *	integer	user	Amount of usage for this record

RolledUpUsage, along with its component RolledUpUnit, is used to maintain the cumulative record of usage over a specified period of time.

RolledUpUsage:

Name	Type	Generated by	Description
subscriptionId	string	system	UUID for the subscription
startDate	string	system	starting date for this record
endDate	string	system	ending date for this record
rolledUpUnits	list	system	List of RolledUpUnit (see next)

RolledUpUnit:

Name	Type	Generated by	Description
unitType	string	system	type of unit represented
amount	integer	system	total amount of usage of this unit

Usage

The APIs in this group support recording and retrieving usage data points.

Record usage for a subscription

Records the daily mount of usage of a specified set of unit types for a given subscription

HTTP Request

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

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 '{"subscriptionId":"365987b2-5443-47e4-a467-c8962fc6995c", "trackingId": "my-unique-tracking-id", "unitUsageRecords":[{"unitType":"chocolate-videos","usageRecords":[{"recordDate":"2013-03-14","amount":1}]}]}' \
    "http://localhost:8080/1.0/kb/usages"

import org.killbill.billing.client.api.gen.UsageApi;
protected UsageApi usageApi;

UUID subscriptionId = UUID.fromString("365987b2-5443-47e4-a467-c8962fc6995c");

UsageRecord usageRecord1 = new UsageRecord();
usageRecord1.setAmount(1L);
usageRecord1.setRecordDate(new LocalDate("2013-03-14"));

UnitUsageRecord unitUsageRecord = new UnitUsageRecord();
unitUsageRecord.setUnitType("chocolate-videos");
unitUsageRecord.setUsageRecords(ImmutableList.<UsageRecord>of(usageRecord1));

SubscriptionUsageRecord usage = new SubscriptionUsageRecord();
usage.setSubscriptionId(subscriptionId);
usage.setUnitUsageRecords(ImmutableList.<UnitUsageRecord>of(unitUsageRecord));

usageApi.recordUsage(usage,
                     requestOptions);

usage_record = KillBillClient::Model::UsageRecordAttributes.new
usage_record.amount = 1
usage_record.record_date = "2013-03-14"

unit_usage_record = KillBillClient::Model::UnitUsageRecordAttributes.new
unit_usage_record.unit_type = "chocolate-videos"
unit_usage_record.usage_records = []
unit_usage_record.usage_records << usage_record

result = KillBillClient::Model::UsageRecord.new
result.subscription_id = "365987b2-5443-47e4-a467-c8962fc6995c"
result.unit_usage_records = []
result.unit_usage_records << unit_usage_record

result.create(user, nil, nil, options)

TODO

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201
< Content-Type: application/json
< Content-Length: 0

no content

no content

no content

Request Body

A SubscriptionUsageRecord.

Query Parameters

none

Response

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

Retrieve usage for a subscription and unit type

Retrieves the usage record for a given subscription, for a specified period of time and a specified unit type

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/usages/{subscriptionId}/{unitType}

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/usages/365987b2-5443-47e4-a467-c8962fc6995c/chocolate-videos?startDate=2012-08-25&endDate=2013-08-26"

import org.killbill.billing.client.api.gen.UsageApi;
protected UsageApi usageApi;

UUID subscriptionId = UUID.fromString("365987b2-5443-47e4-a467-c8962fc6995c");

String unitType = "chocolate-videos";
LocalDate startDate = new LocalDate("2012-08-25");
LocalDate endDate = new LocalDate("2013-08-26");

RolledUpUsage retrievedUsage = usageApi.getUsage(subscriptionId,
                                                 unitType,
                                                 startDate,
                                                 endDate,
                                                 requestOptions);

subscription_id = "365987b2-5443-47e4-a467-c8962fc6995c"
start_date = "2012-08-25"
end_date_ = "2013-08-26"
unit_type = "chocolate-videos"

KillBillClient::Model::RolledUpUsage.find_by_subscription_id_and_type(subscription_id,
                                                                      start_date,
                                                                      end_date,
                                                                      unit_type,
                                                                      options)

TODO

Example Response:

{
  "subscriptionId": "365987b2-5443-47e4-a467-c8962fc6995c",
  "startDate": "2012-08-25",
  "endDate": "2013-08-26",
  "rolledUpUnits": [
    {
      "unitType": "chocolate-videos",
      "amount": 1
    }
  ]
}

class RolledUpUsage {
    subscriptionId: 365987b2-5443-47e4-a467-c8962fc6995c
    startDate: 2012-08-25
    endDate: 2012-08-26
    rolledUpUnits: [class RolledUpUnit {
        unitType: chocolate-videos
        amount: 1
    }]
}

{
  "subscriptionId": "365987b2-5443-47e4-a467-c8962fc6995c",
  "startDate": "2012-08-25",
  "endDate": "2013-08-26",
  "rolledUpUnits": [
    {
      "unitType": "chocolate-videos",
      "amount": 1
    }
  ]
}

TODO

Query Parameters

Name	Type	Required	Default	Description
startDate	date	yes	none	Date of oldest data point to retrieve (see below)
endDate	date	yes	none	Date of newest data point to retrieve (see below)

• startDate, endDate: Data is retrieved beginning on the specified start date up to but not including the specified end date.

Response

IF successful, returns a status code of 200 and a RolledUpUsage object.

Retrieve usage for a subscription

Retrieves the usage record for a given subscription, for a specified period of time and all unit types

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/usages/{subscriptionId}

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/usages/365987b2-5443-47e4-a467-c8962fc6995c?startDate=2012-08-25&endDate=2013-08-26"

import org.killbill.billing.client.api.gen.UsageApi;
protected UsageApi usageApi;

UUID subscriptionId = UUID.fromString("365987b2-5443-47e4-a467-c8962fc6995c");

LocalDate startDate = new LocalDate("2012-08-25");
LocalDate endDate = new LocalDate("2013-08-26");

RolledUpUsage retrievedUsage = usageApi.getAllUsage(subscriptionId,
                                                    startDate,
                                                    endDate,
                                                    requestOptions);

subscription_id = "365987b2-5443-47e4-a467-c8962fc6995c"
start_date = "2012-08-25"
end_date = = "2013-08-26"

KillBillClient::Model::RolledUpUsage.find_by_subscription_id(subscription_id,
                                                             start_date,
                                                             end_date,
                                                             options)

TODO

Example Response:

{
  "subscriptionId": "365987b2-5443-47e4-a467-c8962fc6995c",
  "startDate": "2012-08-25",
  "endDate": "2013-08-26",
  "rolledUpUnits": [
    {
      "unitType": "chocolate-videos",
      "amount": 1
    }
  ]
}

class RolledUpUsage {
    subscriptionId: 365987b2-5443-47e4-a467-c8962fc6995c
    startDate: 2012-08-25
    endDate: 2012-08-26
    rolledUpUnits: [class RolledUpUnit {
        unitType: chocolate-videos
        amount: 1
    }]
}

{
  "subscriptionId": "365987b2-5443-47e4-a467-c8962fc6995c",
  "startDate": "2012-08-25",
  "endDate": "2013-08-26",
  "rolledUpUnits": [
    {
      "unitType": "chocolate-videos",
      "amount": 1
    }
  ]
}

TODO

Query Parameters

Name	Type	Required	Default	Description
startDate	date	yes	none	Date of oldest data point to retrieve (see below)
endDate	date	yes	none	Date of newest data point to retrieve (see below)

• startDate, endDate: Data is retrieved beginning on the specified start date up to but not including the specified end date.

Response

IF successful, returns a status code of 200 and a RolledUpUsage object.

Custom Field

A custom field is an attribute (key-value pair) that may be attached to almost any resource.

This section provides APIs to list all custom fields, search for a specific custom field, and retrieve custom field audit logs. Searching may be based on the custom field id or on its name, value, or resource type. In addition, each resource provides APIs for the applicable CRUD operations: creation, retrieval, updating, and deletion.

Custom Field Resource

A tag resource is associated with a tag definition and attached to another specific resource. The resource object has the following attributes:

Name	Type	Generated by	Description
customFieldId	string	system	UUID for this custom field
objectType	string	user	Type of the object this tag is attached to (e.g. "ACCOUNT")
objectID	string	system	UUID for the object
name	string	user	name of the custom field
value	string	user	value of the custom field
auditLogs	array	system	array of audit log records for this custom field

List all custom fields

Retrieves a list of all custom fields (name and value) with their associated resources and optional audit logs

HTTP Request

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

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns a list of records for all custom fields

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/customFields/pagination"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Search custom fields by ID

Searches for a specific custom field by its ID

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customField/search/{customFieldId}

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns the record for the specified custom field, if it exists

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/customFields/search/13fe6f2c-91af-4635-aa9c-52e04d99b5ec"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Search custom fields by resource type, name, and optional value

Searches for a specific custom field by its resource type, name, and optional value

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customField/search

Query Parameters

Name	Type	Required	Default	Description
objectType	string	true	none	type of resource to search (e.g., "ACCOUNT")
fieldName	string	true	none	name of the custom field to search for
fieldValue	string	false	any value	value of the custom field to search for
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns the record for the specified custom field, if it exists

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/customFields/search?objectType=ACCOUNT&fieldName=importance"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "name": "importance",
    "value": "high",
    "auditLogs": []
  }
]

Audit Logs

Retrieve custom field audit logs with history by custom field id

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/customFields/{customFieldId}/auditLogsWithHistory

Example Request:

    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/customFields/4b498210-b177-4aae-a539-cf594adaa221/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2013-08-01T06:00:00.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "2b3920ae-6b8c-4deb-9ed9-132ff632e692",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:00.000Z",
      "updatedDate": "2013-08-01T06:00:00.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2013-08-01T06:00:01.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "6343d19f-cef0-486a-8114-85c7573639a0",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:01.000Z",
      "updatedDate": "2013-08-01T06:00:01.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "another_test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  },
  {
    "changeType": "DELETE",
    "changeDate": "2013-08-01T06:00:01.000Z",
    "objectType": "CUSTOM_FIELD",
    "objectId": "4b498210-b177-4aae-a539-cf594adaa221",
    "changedBy": "test_custom_fields",
    "reasonCode": null,
    "comments": null,
    "userToken": "9a9343bd-9cba-417b-be17-713ff456b5f7",
    "history": {
      "id": null,
      "createdDate": "2013-08-01T06:00:01.000Z",
      "updatedDate": "2013-08-01T06:00:01.000Z",
      "recordId": 1,
      "accountRecordId": 17,
      "tenantRecordId": 12,
      "fieldName": "Test Custom Field",
      "fieldValue": "another_test_value",
      "objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "CUSTOM_FIELD",
      "historyTableName": "CUSTOM_FIELD_HISTORY"
    }
  }
]

Query Parameters

None.

Returns

Returns a list of custom field logs with history.

Tag

A tag is a label that may be attached to almost any resource. There are two categories of tags: System Tags and User Tags.

Kill Bill provides a small set of predefined System Tags that affect the behavior of the system. For example, AUTO_PAY_OFF prevents the system from initiating automatic payment of an invoice. System Tags may be attached only to specific resource types, and most (including AUTO_PAY_OFF) apply only to Accounts.

The following system tags have been defined:

Tag	tagDefinitionId	Object type	Description
AUTO_PAY_OFF	00000000-0000-0000-0000-000000000001	ACCOUNT	Suspends payments until removed.
AUTO_INVOICING_OFF	00000000-0000-0000-0000-000000000002	ACCOUNT	Suspends invoicing until removed.
OVERDUE_ENFORCEMENT_OFF	00000000-0000-0000-0000-000000000003	ACCOUNT	Suspends overdue enforcement behaviour until removed.
WRITTEN_OFF	00000000-0000-0000-0000-000000000004	INVOICE	Indicates that an invoice is written off. This has no effect on billing or payment.
MANUAL_PAY	00000000-0000-0000-0000-000000000005	ACCOUNT	Indicates that Killbill doesn't process payments for this account. That is, the account uses external payments only.
TEST	00000000-0000-0000-0000-000000000006	ACCOUNT	Indicates that this is a test account.
PARTNER	00000000-0000-0000-0000-000000000007	ACCOUNT	Indicates that this is a partner account.
AUTO_INVOICING_DRAFT	00000000-0000-0000-0000-000000000008	ACCOUNT	Generate account invoices in DRAFT mode.
AUTO_INVOICING_REUSE_DRAFT	00000000-0000-0000-0000-000000000009	ACCOUNT	Use existing draft invoice if exists.

User Tags are defined by the user for any desired purpose and are not interpreted by the system. User Tags must be defined using the Tag Definition APIs below. These tags may be attached to almost any resource type.

This section provides APIs to list all tags, search for a specific tag, and retrieve tag audit logs. In addition, each resource provides APIs for the applicable CRUD operations: creation, retrieval, and deletion.

Tag Resource

A tag resource is associated with a tag definition and attached to another specific resource. The resource object has the following attributes:

Name	Type	Generated by	Description
tagId	string	system	UUID for this specific tag
objectType	string	user	Type of the object this tag is attached to (e.g. "ACCOUNT")
objectID	string	system	UUID for the object
tagDefinitionId	string	system	UUID for the tag definition
tagDefinitionName	string	user	name for the tag definition
auditLogs	array	system	array of audit log records for this tag

List all tags

Retrieves a list of all tags with their associated resources and tag definitions

HTTP Request

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

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns a list of records for all tags

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/tags/pagination"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "tagId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "tagDefinitionId": "1ac0218e-0d2b-4c65-841f-cff8af92a100",
    "tagDefinitionName": "sleepy",
    "auditLogs": []
  }
]

Search tags

Searches for a specific tag

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tags/search/{tagId}

Query Parameters

Name	Type	Required	Default	Description
offset	integer	false	0	starting item in the list
limit	integer	false	100	number of items to return
audit	string	false	"NONE"	"NONE", "MINIMAL", or "FULL"

Returns

Returns the record for the specified tag, if it exists

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://127.0.0.1:8080/1.0/kb/tags/search/13fe6f2c-91af-4635-aa9c-52e04d99b5ec"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "tagId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
    "objectType": "ACCOUNT",
    "objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
    "tagDefinitionId": "1ac0218e-0d2b-4c65-841f-cff8af92a100",
    "tagDefinitionName": "sleepy",
    "auditLogs": []
  }
]

Retrieve tag audit logs

Retrieves audit logs with history for a specific tag

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tags/{tagId}/auditLogsWithHistory

Query Parameters

None.

Returns

Returns a list of tag audit logs with history.

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/tags/26e22dbf7-a493-4402-b1e3-4bec54c39f31/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2013-09-01T06:00:05.000Z",
    "objectType": "TAG",
    "objectId": "6e22dbf7-a493-4402-b1e3-4bec54c39f31",
    "changedBy": "test_fixed_and_recurrring_items",
    "reasonCode": null,
    "comments": "Closing account",
    "userToken": "06d4fa80-f6ab-4760-aa97-2cd4ab83fd37",
    "history": {
      "id": null,
      "createdDate": "2013-09-01T06:00:05.000Z",
      "updatedDate": "2013-09-01T06:00:05.000Z",
      "recordId": 1,
      "accountRecordId": 11,
      "tenantRecordId": 2,
      "tagDefinitionId": "00000000-0000-0000-0000-000000000002",
      "objectId": "037a6b81-f351-4e09-b2ea-f76f2fb0189e",
      "objectType": "ACCOUNT",
      "isActive": true,
      "tableName": "TAG",
      "historyTableName": "TAG_HISTORY"
    }
  }
]

Tag Definition

These APIs manage a tag definition resource object, which provides the definition for a user-defined tag.

Tag Definition Resource

Each tag is associated with a specific tag definition. A tag definition is a schema or template, and a tag is an instance of it. Please refer to the section AccountTags for an overview of tags. The system provides some System tag definitions that can be used to add tags to a particular object. Users may define their own tags; however, when using User Tags, one must first create the associated tag definition.

The tag definition resource includes the following attributes:

Name	Type	Generated by	Description
id	string	system	UUID for the tag definition
isControlTag	boolean	system	True if this is a control tag
name	string	user	Name of the tag definition
description	string	user	Description of the tag definition
applicableObjectTypes	list	user	see below

• applicableObjectTypes: A list giving the name(s) of resource types that can be given this tag.

Tag Definition

The APIs in this group provide the ability to create, retrieve, and delete tag definitions, and also to access their associated audit logs.

Create a tag definition

Creates a new tag definition.

HTTP Request

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

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": "good_customer", "description": "a good customer", "applicableObjectTypes": ["ACCOUNT"]}' \
    "http://127.0.0.1:8080/1.0/kb/tagDefinitions"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 201 
< Location: http://127.0.0.1:8080/1.0/kb/tagDefinitions/93f2bc59-e18d-4a5e-a645-9386c76fc03f
< Content-Type: application/json
< Content-Length: 0

no content

Request Body

A TagDefinition resource object with at least the following attributes: name, description, and applicableObjectTypes. The list of applicableObjectTypes may not be empty.

Query Parameters

none

Response

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

List tag definitions

Lists all tag definitions for this tenant

HTTP Request

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

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/tagDefinitions"

Example Response:

{
    "id": "93f2bc59-e18d-4a5e-a645-9386c76fc03f",
    "isControlTag": false,
    "name": "good_customer",
    "description": "a good customer",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
},
{
    "id": "00000000-0000-0000-0000-000000000001",
    "isControlTag": true,
    "name": "AUTO_PAY_OFF",
    "description": "Suspends payments until removed.",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
},
 ...

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Response

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

Retrieve a tag definition by its ID

Retrieves an existing tag definition.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}

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/tagDefinitions/93f2bc59-e18d-4a5e-a645-9386c76fc03f"

Example Response:

{
    "id": "93f2bc59-e18d-4a5e-a645-9386c76fc03f",
    "isControlTag": false,
    "name": "good_customer",
    "description": "a good customer",
    "applicableObjectTypes": [
      "ACCOUNT"
    ],
    "auditLogs": []
}

Query Parameters

Name	Type	Required	Default	Description
audit	string	no	"NONE"	Level of audit information to return

Audit information options are "NONE", "MINIMAL" (only inserts), or "FULL".

Returns

If successful, returns a status code of 200 and a tag definition object.

Delete a tag definition

Deletes a tag definition.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -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/tagDefinitions/93f2bc59-e18d-4a5e-a645-9386c76fc03f"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 
< Content-Type: application/json

Query Parameters

None.

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 tag definition audit logs with history by id

Retrieves a list of audit log records showing events that occurred involving changes to a specified tag definition. History information is included with each record.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/tagDefinitions/{tagDefinitionId}/auditLogsWithHistory

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/tagDefinitions/92991586-df8a-4d8d-9d55-61172c52fa45/auditLogsWithHistory"

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-26T01:56:48.000Z",
    "objectType": "TAG_DEFINITION",
    "objectId": "92991586-df8a-4d8d-9d55-61172c52fa45",
    "changedBy": "demo",
    "reasonCode": "demo",
    "comments": "demo",
    "userToken": "039f01ea-460a-4edd-bfbc-39a68149cad2",
    "history": {
      "id": null,
      "createdDate": "2019-02-26T01:56:48.000Z",
      "updatedDate": "2019-02-26T01:56:48.000Z",
      "recordId": 1,
      "accountRecordId": 1,
      "tenantRecordId": 1,
      "name": "good_customer",
      "applicableObjectTypes": "ACCOUNT",
      "description": "a good customer",
      "isActive": true,
      "tableName": "TAG_DEFINITIONS",
      "historyTableName": "TAG_DEFINITION_HISTORY"
    }
  }
]

Query Parameters

None.

Response

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

Admin

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

• Administrative APIs to fix improper states
• Operational APIs such as adding hosts in and out of rotation, clearing internal caches, etc.
• APIs to retrieve low level information from the system

Administrative Apis

Miscellaneous administrative APIs

Trigger an invoice generation for all parked accounts

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

HTTP Request

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    "http://127.0.0.1:8080/1.0/kb/admin/invoices"

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

adminApi.triggerInvoiceGenerationForParkedAccounts(offset, 
                                                   limit, 
                                                   requestOptions);

ofset = 0
limit = 100
user = "demo"

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

adminApi = killbill.api.AdminApi()

adminApi.trigger_invoice_generation_for_parked_accounts('test', api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/json

no content

no content

no content

Query Parameters

| Name | Type | Required | Default | Description | | ---- | -----| -------- | ----------- | | offset | long | no | 0 | starting offset for the page | | limit | long | no | 100 | max results on this page |

Returns

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

Update the state of a paymentTransaction and associated payment

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

HTTP Request

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

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    "http://127.0.0.1:8080/1.0/kb/admin/payments/864c1418-e768-4cd5-a0db-67537144b685/transactions/864c1418-e768-4cd5-a0db-67537144b685"

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

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

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

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

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

payment_id = "6cb944a-b308-4488-b046-4b4d61d375a6"
transaction_id = "8gb944a-b308-4488-b046-4b4d61d375r3"
transaction_status = "AUTH_FAILED"
user =  "demo"
reason = nil
comment = nil

KillBillClient::Model::Admin.fix_transaction_state(payment_id, 
                                                   transaction_id, 
                                                   transaction_status, 
                                                   user, 
                                                   reason, 
                                                   comment, 
                                                   options)

adminApi = killbill.api.AdminApi()

payment_id = '8gb944a-b308-4488-b046-4b4d61d375r3'
payment_transaction_id = '6cb944a-b308-4488-b046-4b4d61d375a6'
body = AdminPayment(transaction_status='AUTH_FAILED')
created_by = 'demo'

adminApi.update_payment_transaction_state(payment_id, 
                                          payment_transaction_id, 
                                          body, 
                                          created_by,
                                          api_key, 
                                          api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Request Body

An `AdminPayment' object

Query Parameters

None.

Returns

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

Operational Apis

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

Invalidate a specific cache, or invalidate all caches

Invalidates a specified cache. If no cache is specified, it invalidates all Kill Bill caches on the server.

HTTP Request

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

Example Request:

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

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

String cacheName = null;

adminApi.invalidatesCache(cacheName, requestOptions);

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

adminApi = killbill.api.AdminApi()

adminApi.invalidates_cache(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

Name	Type	Required	Default	Description
cacheName	string	no	all caches	cache name

Returns

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

Invalidate Caches for an Account

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

HTTP Request

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

Example Request:

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

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

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

adminApi.invalidatesCacheByAccount(accountId, requestOptions);

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

adminApi = killbill.api.AdminApi()
account_id = '2ad52f53-85ae-408a-9879-32a7e59dd03d'

adminApi.invalidates_cache_by_account(account_id, api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Invalidate Caches for a Tenant

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

HTTP Request

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

Example Request:

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

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

adminApi.invalidatesCacheByTenant(requestOptions);

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

adminApi = killbill.api.AdminApi()

adminApi.invalidates_cache_by_tenant(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Returns

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

Put the host back into rotation

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

HTTP Request

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

Example Request:

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

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

adminApi.putInRotation(requestOptions);

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

adminApi = killbill.api.AdminApi()

adminApi.put_in_rotation(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Remove a server from the rotation

Removes a server from the rotation during a deployment.

HTTP Request

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

Example Request:

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

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

adminApi.putOutOfRotation(requestOptions);

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

adminApi = killbill.api.AdminApi()

adminApi.put_out_of_rotation(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 204 No Content
< Content-Type: application/json

no content

no content

no content

Query Parameters

None.

Response

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

Low Level View Apis

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

Get queue entries

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

HTTP Request

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

Example Request:

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

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


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

account_id = "864c1418-e768-4cd5-a0db-67537144b685"
KillBillClient::Model::Admin.get_queues_entries(account_id, options)

adminApi = killbill.api.AdminApi()

adminApi.get_queue_entries(api_key, api_secret)

Example Response:

# Subset of headers returned when specifying -v curl option
< HTTP/1.1 200 OK
< Content-Type: application/octet-stream

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

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

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

Query Parameters

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

Returns

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