NAV Navbar
shell java ruby python
  • Using Kill Bill APIs
  • Tenant
  • Catalog
  • Account
  • Payment Method
  • Subscription
  • Bundle
  • Invoice
  • Credit
  • Payment
  • Payment Transaction
  • Invoice Payment
  • Usage
  • Custom Field
  • Tag
  • Tag Definition
  • Admin
  • 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:

    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:

    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:

    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:

    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:

    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:

    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:

    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.

    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:

    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:

    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:

    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

    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:

    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.

    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:

    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 JSON string representing the custom field object to be added.

    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 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 JSON string representing a list of custom fields to substitute for the existing ones. 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.

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