Subscription

A Subscription in Kill Bill entitles a customer to the use of a product or service for a period of time in exchange for a specified payment. Every subscription belongs to a Bundle that is associated with a given customer Account.

Subscriptions are created by specifying a Plan from the catalog, and an effective date on which to start. The Plan identifies the Product subscribed along with the terms of service and of billing. These attributes are used by the system to drive the generation of invoices. Kill Bill offers two parallel views of the subscription: one to track the entitlement, i.e the service associated with the subscription, and one to track the billing. These views address the following questions:

  • Given a date, how much should we invoice ?
  • Given a date, is the service available to the customer?

For most use cases, those two views are one and the same; the customer gets invoiced for what she consumes.

Please refer to our subscription manual for more details.

Subscription Resource

The Subscription resource represents a subscription. The attributes contained in the subscription resource are the following:

Name Type Generated by Description
accountId string system UUID for the account
bundleId string system UUID for the bundle
subscriptionId string system UUID for this subscription
externalKey string user Optional external key for the subscription
bundleExternalKey string user Optional external key for the bundle
startDate date user Datetime the service (entitlement) starts
productName string user Name of the product subscribed (from catalog)
productCategory string user Product catgory (see notes below)
billingPeriod string user Billing period (see notes below)
phaseType string user Type of the current plan phase (see notes below)
priceList string user Name of the current price list (from catalog)
planName string user Name of the current plan (from catalog)
state string system Current state of the subscription (see notes below)
sourceType string system Kind of subscription (see notes below)
cancelledDate date user Datetime when the service stopped, or will stop
chargedThroughDate date system Date up to which the subscription has been invoiced (see notes below)
billingStartDate date user Datetime on which the system starts invoicing
billingEndDate date user Datetime on which the system ends invoicing
billCycleDayLocal integer user or system Day of the month on which invoices are generated, if applicable (see notes below)
events list system List of subscription events corresponding to this subscription. See SubscriptionEvent resource below.
prices list user list of prices, one for each phase in the plan
priceOverrides list user list of prices if this subscription has price overrides (see notes below)
quantity integer user quantity of subscriptions (see notes below)
auditlogs array system Array of audit log records for this invoice

productCategory: possible values are BASE, ADD_ON, or STANDALONE

billingPeriod: possible values are DAILY, WEEKLY, BIWEEKLY, THIRTY_DAYS, THIRTY_ONE_DAYS, SIXTY_DAYS, NINETY_DAYS, MONTHLY, BIMESTRIAL (bimonthly), QUARTERLY, TRIANNUAL, BIANNUAL, ANNUAL, SESQUIENNIAL, BIENNIAL, TRIENNIAL, or NO_BILLING_PERIOD

phaseType: possible values are: TRIAL, DISCOUNT, FIXEDTERM, or EVERGREEN

state: possible values are:

  • PENDING: The subscription is not yet created.
  • ACTIVE: The subscription is currently active.
  • BLOCKED: The subscription is currently paused.
  • CANCELLED: The subscription has been cancelled.
  • EXPIRED: The subscription has expired. This state is applicable only for subscriptions with a FIXEDTERM phase.

sourceType: possible values are NATIVE, MIGRATED, or TRANSFERRED

chargedThroughDate: The date up to which the entitlement for this subscription has been invoiced. For IN_ADVANCE billing mode, this date will often be in the future; for IN_ARREAR, this date will often be in the past. For example,

  1. A subscription is billed each month, on the 15th, in advance. If we check on May 31, the chargedThroughDate will be June 15th, 15 days ahead. If the subscription is ended on May 31, a prorated credit will need to be issued.

  2. A subscription is billed quarterly, in arrears, on the 10th of Feb., May, Aug., and Nov. If we check on Jul. 20, the chargedThroughDate will be May 10, over 2 months earlier. If the subscription is cancelled on Jul. 20, an additional invoice will need to be issued.

These use cases assume that invoicing is up to date. If AUTO_INVOICING_OFF is set, invoicing relies on a manual process and may be late. In that situation the first use case may require a smaller credit or none at all, while the second case will have a larger amount to be billed to close out the subscription.

billCycleDayLocal: this value is either the overridden subscription billCycleDay (in case of BCD change) or the value at the subscription, bundle or account level (depending on the catalog billing alignments). For ACCOUNT billing alignments, if the account level billCycleDay hasn't been set yet, the value returned would be null.

priceOverrides: List of overridden prices for specific plan phases. Can be specified to override the fixed/recurring price in the catalog for a particular phase. For example, suppose you are creating a subscription corresponding to a plan that has an EVERGREEN phase with a recurring price of $100. You can specify an overridden price of 200 while creating the subscription by specifying a priceOverrides object as follows:

"priceOverrides": [ { "planName": "shotgun-monthly", "phaseType": "DISCOUNT", "fixedPrice": null, "recurringPrice": 150.00, "usagePrices": [] }

quantity: An integer value that specifies the quantity of subscription. The default value is 1. The corresponding invoice is generated as per the quantity. So if price=$20/mo, quantity=$2 => invoiceItem recurring amount=$40.

SubscriptionEvent Resource

The SubscriptionEvent resource represents an event on a subscription. An event is generated when a subscription is created, cancelled, paused, resumed,etc. In addition, events are also generated when there is a phase change or plan change.

Name Type Generated by Description
eventId string system UUID for this subscription event
billingPeriod string user Billing period (see notes above)
effectiveDate DateTime system DateTime that the event is effective
catalogEffectiveDate DateTime user The effective date of the underlying catalog.
plan string user Name of the current plan (from catalog)
product date user Name of the product subscribed (from catalog)
priceList string user Name of the current price list (from catalog)
phase string user Name of the current phase (from catalog)
eventType string user Type of event (see notes below)
isBlockedBilling boolean user Boolean flag that indicates whether billing should be blocked
isBlockedEntitlement boolean user Boolean flag that indicates whether the entitlement should be blocked
serviceName string user Name of the service that inserts the event
serviceStateName string user Name of the event state

eventType: possible event types are START_ENTITLEMENT, START_BILLING, PAUSE_ENTITLEMENT, PAUSE_BILLING, RESUME_ENTITLEMENT, RESUME_BILLING, PHASE, CHANGE, STOP_ENTITLEMENT, STOP_BILLING, SERVICE_STATE_CHANGE. See also SubscriptionEventType.

Subscriptions

These endpoints support the basic CRUD operations on Subscriptions.

Create a subscription

This API creates a base product subscription. It also creates a bundle to contain the subscription. See Bundle for further information.

HTTP Request

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

Request Body

A subscription resource object specifying accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

It can also include the following optional fields:

  • phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
  • externalKey - External key corresponding to the subscription.
  • billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
  • bundleId - Id of the bundle in which to create this subscription. Can be specified only while invoking this method for an addon subscription.

Query Parameters

Name Type Required Default Description
entitlementDate string no immediately Date/DateTime at which the entitlement (service) starts in yyyy-mm-dd/yyyy-mm-ddThh:mm:ssZ format.
billingDate string no immediately Date/DateTime at which the billing starts in yyyy-mm-dd/yyyy-mm-ddThh:mm:ssZ format.
renameKeyIfExistsAndUnused boolean no true If true, rename external key if it exists and is unused
migrated boolean no false If true, subscription is migrated
skipResponse boolean no false TODO
callCompletion boolean no false see below
callTimeoutSec long no unlimited? Timeout in seconds (see below)

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Other Notes:

  • Specifying the startDate/billingStartDate as part of the request body has no effect, these dates need to be passed as query parameters (entitlementDate/billingDate).
  • The entitlementDate drives the subscription state. So, if a subscription is created with a future entitlementDate, its state remains PENDING until the date is reached after which it becomes ACTIVE.
  • When a DateTime is specified corresponding to the entitlementDate/billingDate parameters, it may or may not include a timezone component. If a timezone is included (like entitlementDate=2024-03-10T11:00:00-08:00), the specified timezone (PST in this case) is used. If timezone is not included (like entitlementDate=2024-03-07T11:15), it defaults to UTC.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains the new subscription id.

Example Request:


# With planName
curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
            "externalKey": "somethingSpecial",
            "planName": "super-monthly"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions" 

# With productName, productCategory and billingPeriod

    curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
          "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
            "externalKey": "somethingSpecial", 
            "productName": "Test", 
            "productCategory": "BASE",  
            "billingPeriod": "MONTHLY",
            "priceList": "DEFAULT"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions"    

# With priceOverrides

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "accountId": "944bf633-88a8-4575-96b5-80bf0a0fdfec",
            "planName": "pistol-monthly-notrial",
             "priceOverrides": [

        {
            "planName": "pistol-monthly-notrial",
            "phaseType": "EVERGREEN",
            "fixedPrice": null,
            "recurringPrice": 400.00,
            "usagePrices": []
        }       
    ]
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions"

# With Datetime (No Timezone, so taken to be UTC)

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "accountId": "325fbe1c-7c35-4d96-a4e5-2cbaabe218c6",
            "planName": "pistol-monthly-notrial"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions?billingDate=2023-02-07T11:15&entitlementDate=2023-02-07T11:15" 

# Datetime with timezone

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "accountId": "325fbe1c-7c35-4d96-a4e5-2cbaabe218c6",
            "planName": "pistol-monthly-notrial"
        }' \
    "http://127.0.0.1:8080/1.0/kb/subscriptions?billingDate=2024-03-10T11:00:00-08:00&entitlementDate=2024-03-10T11:00:00-08:00"

Create a subscription with addon products

This API creates a subscription bundle with base and addon product subscriptions. It can also be used to add an addon subscription to a base subscription in which case the bundle id of the base subscription must be specified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns

Request Body

A subscription resource object corresponding to the base subscription and zero or more subscription resource objects corresponding to add-on subscriptions need to be specified. Alternatively, only a list of add-on subscription resource objects may be specified along with the base subscription bundle id. Each subscription resource object needs to include accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

In addition, each subscription resource can also include the following optional fields:

  • phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
  • externalKey - External key corresponding to the subscription.
  • billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
  • bundleId - Id of the bundle in which to create this subscription. Can be specified only with an add-on subscription resource.

Query Parameters

Name Type Required Default Description
entitlementDate string no immediately Date at which the entitlement (sevice) starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
billingDate string no immediately Date at which the billing starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
renameKeyIfExistsAndUnused boolean no true If true, rename external key if it exists and is unused
migrated boolean no false If true, subscription is migrated
skipResponse boolean no false TODO
callCompletion boolean no false see below
callTimeoutSec long no unlimited? Timeout in seconds (see below)
pluginProperty array of strings false omit list of plugin properties, if any

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains the new bundle id.

Example Request:

# create a subscription with addon
curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
            "externalKey": "something",
            "bundleExternalKey": "somethingAlso",
            "productName": "Sports",
            "productCategory": "BASE",
            "billingPeriod": "MONTHLY",
            "priceList": "DEFAULT"
        },
        {
          "accountId": "581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
          "productName": "OilSlick",
          "productCategory": "ADD_ON",
          "billingPeriod": "MONTHLY",
          "priceList": "DEFAULT"
        }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns' 

OR

# create an addon on an existing base subscription
curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[

        {
          "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
          "planName": "remotecontrol-monthly",
          "bundleId":"b4709feb-bd14-455a-bbb4-57a758498791"
        }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionWithAddOns'

Create multiple subscriptions with addon products

This API creates multiple subscriptions with base and addon product subscriptions. It can also be used to add an addon subscription to a base subscription in which case the bundle id of the base subscription must be specified.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns

Request Body

One or more subscription resource object corresponding to the base subscriptions need to be specified. Additional, each base subscription resource object can include zero or more subscription resource objects corresponding to add-on subscriptions. Alternatively, only a list of add-on subscription resource objects may be specified along with the base subscription bundle id. Each subscription resource object needs to include accountId and either the planName or a combination of productName, productCategory,billingPeriod and priceList.

In addition, each subscription resource can also include the following optional fields:

  • phaseType - Target phase type. Specifying this field causes the subscription to start with this phase.
  • externalKey - External key corresponding to the subscription.
  • billCycleDayLocal - Per-subscription BCD. Specifying this value allows realigning the billing with the specified date.
  • bundleId - Id of the bundle in which to create this subscription. Can be specified only with an add-on subscription resource.

Query Parameters

Name Type Required Default Description
entitlementDate string no immediately Date at which the entitlement (sevice) starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
billingDate string no immediately Date at which the billing starts in yyyy-mm-dd format. If specified, applies both to base and add-on products.
renameKeyIfExistsAndUnused boolean no true If true, rename external key if it exists and is unused
migrated boolean no false If true, subscription is migrated
skipResponse boolean no false TODO
callCompletion boolean no false see below
callTimeoutSec long no unlimited? Timeout in seconds (see below)
pluginProperty array of strings false omit list of plugin properties, if any

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains URL to fetch the newly created bundles.

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "886adb60-be70-40c8-b97d-1f8ecbc30a64",
                "externalKey": "base",
                "productName": "Sports",
                "productCategory": "BASE",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              },
              {
                "accountId": "886adb60-be70-40c8-b97d-1f8ecbc30a64",
                "productName": "OilSlick",
                "productCategory": "ADD_ON",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              }
            ]
          },
           {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
                "externalKey": "createSubscriptionsWithAddOns3",
                "productName": "Test",
                "productCategory": "BASE",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              },
              {
                "accountId": "59afd9fe-e98d-4fb3-b5bf-21d4a2b036cd",
                "productName": "TestAO",
                "productCategory": "ADD_ON",
                "billingPeriod": "MONTHLY",
                "priceList": "DEFAULT"
              }
            ]
          }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns' 

OR 

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[
          {
            "baseEntitlementAndAddOns": [
              {
                "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
                "planName": "remotecontrol-monthly",  
                "bundleId":"a8b4022c-e38c-4336-ad2f-ee15c5e18d12"
              }
            ]
          },
          {
            "baseEntitlementAndAddOns": [

              {
                "accountId": "1f635c3d-fc24-4fa8-81e0-ab646882807a",
                "planName": "remotecontrol-monthly",
                "bundleId":"06892885-c276-4cf9-8311-ef0b8a2e364b"
              }
            ]
          }
        ]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/createSubscriptionsWithAddOns'

Retrieve a subscription by id

This API retrieves a subscription resource object based on its subscription id

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

Query Parameters

Name Type Required Default Description
audit string no "NONE" "NONE", "MINIMAL" (only inserts), or "FULL"

Response

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

Example Request:

curl \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/d4a919f4-7459-494f-85e5-af8880f63e90'

Example Response:

{
    "accountId":"581d86fc-7cfc-46f2-b6d4-4dbc1d98beb3",
    "bundleId":"3b7a754c-4fe3-49a4-a56c-c8f56fc4116c",
    "subscriptionId":"d4a919f4-7459-494f-85e5-af8880f63e90",
    "externalKey":"somethingSpecial",
    "bundleExternalKey":"somethingAlsoSpecial",
    "startDate":"2018-07-19",
    "productName":"Super",
    "productCategory":"BASE",
    "billingPeriod":"MONTHLY",
    "phaseType":"TRIAL",
    "priceList":"DEFAULT",
    "planName":"super-monthly",
    "state":"ACTIVE",
    "sourceType":"NATIVE",
    "cancelledDate":null,
    "chargedThroughDate":"2018-07-19",
    "billingStartDate":"2018-07-19",
    "billingEndDate":null,
    "billCycleDayLocal":18,
    "events":
    [
        {
            "eventId":"d1fc7c9a-bdcd-447c-90f4-72c8de37d457",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-07-19",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"START_ENTITLEMENT",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement-service",
            "serviceStateName":"ENT_STARTED",
            "phase":"super-monthly-trial",
            "auditLogs":[]
        },
        {
            "eventId":"e1cea834-9c21-450a-8ff5-8e1ebef705d1",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-07-19",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"START_BILLING",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"billing-service",
            "serviceStateName":"START_BILLING",
            "phase":"super-monthly-trial",
            "auditLogs":[]
        },
        {
            "eventId":"c9045227-4638-46ca-9a4a-2d3086168505",
            "billingPeriod":"MONTHLY",
            "effectiveDate":"2018-08-18",
            "plan":"super-monthly",
            "product":"Super",
            "priceList":"DEFAULT",
            "eventType":"PHASE",
            "isBlockedBilling":false,
            "isBlockedEntitlement":false,
            "serviceName":"entitlement+billing-service",
            "serviceStateName":"PHASE",
            "phase":"super-monthly-evergreen",
            "auditLogs":[]
        }
    ],
    "priceOverrides":null,
    "prices":
    [
        {
            "planName":"super-monthly",
            "phaseName":"super-monthly-trial",
            "phaseType":"TRIAL",
            "fixedPrice":0,
            "recurringPrice":null,
            "usagePrices":[]
        },
        {
            "planName":"super-monthly",
            "phaseName":"super-monthly-evergreen",
            "phaseType":"EVERGREEN",
            "fixedPrice":null,
            "recurringPrice":1000.00,
            "usagePrices":[]
        }
    ],
    "auditLogs":[]}

Retrieve a subscription by key

This API retrieves a subscription resource object based on its external key

HTTP Request

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

Query Parameters

Name Type Required Default Description
externalKey String yes none The subscription external key
audit string no "NONE" "NONE", "MINIMAL" (only inserts), or "FULL"

Response

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

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    'http://localhost:8080/1.0/kb/subscriptions?externalKey=somethingSpecial'

Example Response:

{
  "accountId": "1f979085-1765-471b-878a-5f640db4d831",
  "bundleId": "8815e8c0-afab-41b9-b793-cb8fef2382e4",
  "bundleExternalKey": "8815e8c0-afab-41b9-b793-cb8fef2382e4",
  "subscriptionId": "8e5c5339-1cad-46c6-ab18-3d5ddc1b2414",
  "externalKey": "somethingSpecial",
  "startDate": "2020-01-08",
  "productName": "Pistol",
  "productCategory": "BASE",
  "billingPeriod": "MONTHLY",
  "phaseType": "EVERGREEN",
  "priceList": "notrial",
  "planName": "pistol-monthly-notrial",
  "state": "ACTIVE",
  "sourceType": "NATIVE",
  "cancelledDate": null,
  "chargedThroughDate": "2020-05-08",
  "billingStartDate": "2020-01-08",
  "billingEndDate": null,
  "billCycleDayLocal": 8,
  "events": [
    {
      "eventId": "1d24928e-790d-4dc9-8a88-c4eaa56de392",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2020-01-08",
      "plan": "pistol-monthly-notrial",
      "product": "Pistol",
      "priceList": "notrial",
      "eventType": "START_ENTITLEMENT",
      "isBlockedBilling": false,
      "isBlockedEntitlement": false,
      "serviceName": "entitlement-service",
      "serviceStateName": "ENT_STARTED",
      "phase": "pistol-monthly-notrial-evergreen",
      "auditLogs": []
    },
    {
      "eventId": "3aaa3239-2bc6-4f04-977b-fce5de098af8",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2020-01-08",
      "plan": "pistol-monthly-notrial",
      "product": "Pistol",
      "priceList": "notrial",
      "eventType": "START_BILLING",
      "isBlockedBilling": false,
      "isBlockedEntitlement": false,
      "serviceName": "billing-service",
      "serviceStateName": "START_BILLING",
      "phase": "pistol-monthly-notrial-evergreen",
      "auditLogs": []
    }
  ],
  "priceOverrides": null,
  "prices": [
    {
      "planName": "pistol-monthly-notrial",
      "phaseName": "pistol-monthly-notrial-evergreen",
      "phaseType": "EVERGREEN",
      "fixedPrice": null,
      "recurringPrice": 19.95,
      "usagePrices": []
    }
  ],
  "auditLogs": []
}

Update the BCD associated with a subscription

This API allows you to change the Bill Cycle Date, BCD, for a given subscription. This only applies to subscriptions whose recurring term is month based -- e.g MONTHLY, ANNUAL, ...

For example if a given subscription was invoiced on the 1st, then one could use this API to realign invoicing, let's say on the 16th.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/bcd

Request Body

The new BCD needs to be specified in the request body via the billCycleDayLocal field.

Query Parameters

Name Type Required Default Description
effectiveFromDate string no immediate Date on which this change becomes effective in yyyy-mm-dd format.
forceNewBcdWithPastEffectiveDate boolean no false See below

By default the effective date must be in the future so as to not modify existing invoices. Setting forceNewBcdWithPastEffectiveDate to true allows the date to be set in the past.

Secondly, even after this endpoint is executed, the Retrieve a Subscription endpoint will still return the old BCD until an invoice is generated on the new BCD.

Response

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

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ "billCycleDayLocal": 16 }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/bcd'

Update the subscription quantity

This API allows you to change the subscription quantity.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/quantity

Request Body

The quantity needs to be specified in the request body via the quantity field.

Query Parameters

Name Type Required Default Description
effectiveFromDate string no immediate Date on which this change becomes effective in yyyy-mm-dd format.
forceNewQuantityWithPastEffectiveDate boolean no false See below

By default the effective date must be in the future so as to not modify existing invoices. Setting forceNewQuantityWithPastEffectiveDate to true allows the date to be set in the past.

Response

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

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "quantity": "2" 
        }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/c20715fa-8d69-488d-a094-51da0cdf999b/quantity'

Change subscription plan

This API allows you to upgrade or downgrade a given subscription to a new Plan.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

Request Body

A subscription resource object specifying either the planName or a combination of productName, billingPeriod and priceList.

Query Parameters

Name Type Required Default Description
billingPolicy string no default Billing policy that will be used to make this change effective (see below)
requestedDate string no immediate Date/DateTime at which this change should become effective in yyyy-mm-dd/yyyy-mm-ddThh:mm:ssZ format.
callCompletion boolean no false see below
callTimeoutSec long no unlimited? Timeout in seconds (see below)
pluginProperty array of strings false omit list of plugin properties, if any

billingPolicy: Possible values are START_OF_TERM, END_OF_TERM, IMMEDIATE, or ILLEGAL

requestedDate: This date is only used if no billingPolicy was specified.

Changing the plan associated to a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Other Notes:

  • When a DateTime is specified corresponding to the requestedDate parameter, it may or may not include a timezone component. If a timezone is included (like entitlementDate=2024-03-10T11:00:00-08:00), the specified timezone (PST in this case) is used. If timezone is not included (like entitlementDate=2024-03-07T11:15), it defaults to UTC.

Response

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

Example Request:

# With productName, billingPeriod, priceList
curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "productName": "Sports", 
            "billingPeriod": "MONTHLY", 
            "priceList": "DEFAULT"
        }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712'

# with planName
curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "planName": "sports-monthly"
        }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/e1868fa6-ea97-493e-870d-50787f4b5921'

# with price overrides
curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{
            "planName": "shotgun-monthly",
            "priceOverrides": [
            {
                "planName": "shotgun-monthly",
                "phaseType": "EVERGREEN",
                "fixedPrice": null,
                "recurringPrice": 400,
                "usagePrices": []
            }
        ]
}' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/5aa1c9e6-bc90-46ca-a925-8f9a48b9dc7f'

Undo a pending change plan on a subscription

This endpoint allows a pending Plan change (plan change request with a future effective date) for a given subscription to be canceled. Note that if the plan change is already effective, then it cannot be undone.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/undoChangePlan

Query Parameters

Query Parameters

Name Type Required Default Description
pluginProperty array of strings false omit list of plugin properties, if any

Response

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

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/undoChangePlan'

Cancel a subscription

This API cancels an existing subscription.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}

Query Parameters

Name Type Required Default Description
requestedDate string no immediate Date/DateTime at which this change should become effective in yyyy-mm-dd/yyyy-mm-ddThh:mm:ssZ format.
entitlementPolicy string no IMMEDIATE entitlement policy (see below)
billingPolicy string no default policy from catalog if present, otherwise END_OF_TERM billing policy (see below)
useRequestedDateForBilling boolean no false use requestedDate for billing
callCompletion boolean no false see below
callTimeoutSec long no unlimited? Timeout in seconds (see below)
pluginProperty array of strings false omit list of plugin properties, if any

entitlementPolicy: Possible values are IMMEDIATE, END_OF_TERM

billingPolicy: Possible values are START_OF_TERM, END_OF_TERM, or IMMEDIATE

Creating a subscription often triggers the creation of an invoice, and associated with this there is often a payment (against the invoice). If callCompletion is true, the call to this API will be delayed until the invoice is created and/or the payment is processed. However, the maximum delay in seconds will be given by callTimeoutSec.

Since we offer the ability to control the cancelation date for both entitlement (service) and billing either through policies, dates or null values (now), it is important to understand how those parameters work:

  • If entitlementPolicy has been defined, the requestedDate is ignored, and we either default to the catalog defined billingPolicy for this Plan, or use the one provided in this API.
  • If not, the requestedDate is used to compute the entitlement cancelation date, and the null value means change should be immediate. The billing date will then be computed the following way:
    • If billingPolicy has been specified, it is used to compute the billing cancelation date
    • If billingPolicy has not been specified, we either use the requestedDate when useRequestedDateForBilling is true or default to the catalog defined billingPolicy for this Plan

So, the common use case would require the following:

  • Immediate cancelation: This will create a prorated credit unless this aligns with the subscription charged through date (CTD), that is, the date up to which it was invoiced, and then from an entitlement point of view it will deactivate service immediately. In order to achieve this result, one can pass the following parameters: entitlementPolicy=IMMEDIATE and billingPolicy=IMMEDIATE; alternatively passing no parameters and therefore a null requestedDate would produce the same result.
  • EOT cancelation: This will not create any proration and will keep the service active until the end of the period (CTD). In order to achieve this result, one can pass the following parameters: entitlementPolicy=END_OF_TERM and billingPolicy=END_OF_TERM.

The reason for all this complexity is to allow to control entitlement and billing date separately, and also avoid users to have to compute dates to achieve certain behavior by relying on well defined policies.

Other Notes:

  • If a subscription is created with a future date and if the cancel method is invoked for immediate cancellation, the cancellation takes effect only after the subscription creation date is reached. Thus, the subscription remains in PENDING state until the subscription creation date is reached after which it is moved to the CANCELLED state.
  • When a DateTime is specified corresponding to the requestedDate parameter, it may or may not include a timezone component. If a timezone is included (like entitlementDate=2024-03-10T11:00:00-08:00), the specified timezone (PST in this case) is used. If timezone is not included (like entitlementDate=2024-03-07T11:15), it defaults to UTC.

Returns

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

Example Request:

curl  -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712'

Un-cancel a subscription

This endpoint allows you to undo a pending cancellation (cancellation request with a future effective date) for a given subscription.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/uncancel

Query Parameters

Name Type Required Default Description
pluginProperty array of strings false omit list of plugin properties, if any

Returns

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

Example Request:

curl \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/uncancel'

Blocking State

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

Block a subscription

Provides a low level interface to add a BlockingState event for this subscription.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/block

Request Body

A blocking state resource representing the intended new blocking state.

Query Parameters

Name Type Required Default Description
requestedDate string no immediate Date/DateTime to begin blocking in yyyy-mm-dd/yyyy-mm-ddThh:mm:ssZ format.

Other Notes:

  • When a DateTime is specified corresponding to the requestedDate parameter, it may or may not include a timezone component. If a timezone is included (like entitlementDate=2024-03-10T11:00:00-08:00), the specified timezone (PST in this case) is used. If timezone is not included (like entitlementDate=2024-03-07T11:15), it defaults to UTC.

Response

If successful, returns a status code of 201 and an empty body. In addition, a Location header is returned which contains the URL to retrieve the subscription blocking states for the account.

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '{ 
            "stateName": "STATE",
            "service": "ServiceStateService",
            "isBlockChange": false,
            "isBlockEntitlement": false,
            "isBlockBilling": false
    }' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/block' 

{
  "blockedId": "943c4fd0-9000-4975-a3a8-09712223e1f8",
  "stateName": "STATE1",
  "service": "ServiceStateService",
  "isBlockChange": false,
  "isBlockEntitlement": false,
  "isBlockBilling": true,
  "effectiveDate": "2020-07-18T18:22:30.376Z",
  "type": "SUBSCRIPTION"
}

Custom Fields

Custom fields are {key, value} attributes that can be attached to any customer resources. For more on custom fields see Custom Fields. These endpoints manage custom fields associated with Subscription objects.

Add custom fields to subscription

Adds one or more custom fields to a subscription object. Existing custom fields are not disturbed.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

Request Body

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

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

Query Parameters

None.

Response

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[{ 
            "name": "Test Custom Field",
            "value": "test_value"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields'

Retrieve subscription custom fields

Returns any custom field objects associated with the specified subscription

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

Query Parameters

Name Type Required Default Description
audit string no "NONE" Level of audit information to return:"NONE", "MINIMAL" (only inserts), or "FULL"

Response

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

Example Request:

curl \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields'

Example Response:

[
    {
        "customFieldId":"439ed0f8-9b37-4688-bace-e2595b1d3801",
        "objectId":"77e23878-8b9d-403b-bf31-93003e125712",
        "objectType":"SUBSCRIPTION",
        "name":"Test Custom Field",
        "value":"test_value",
        "auditLogs":[]
    }
]

Modify custom fields for a subscription

Modifies the value of one or more existing custom fields associated with a subscription. Note that it is not possible to modify the name of a custom field, it is only possible to modify its value.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

Request Body

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

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

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

Query Parameters

None.

Response

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

Example Request:

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[{ 
            "customFieldId": "439ed0f8-9b37-4688-bace-e2595b1d3801",
            "value": "NewValue"
    }]' \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields'

Remove custom fields from subscription

Delete one or more custom fields from a subscription. It accepts query parameters corresponding to the custom field ids to be deleted. If no query parameters are specified, it deletes all the custom fields corresponding to the subscription.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/customFields

Query Parameters

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

Response

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/customFields?customField=439ed0f8-9b37-4688-bace-e2595b1d3801'

Tags

See section Tags for an introduction.

Note: None of the system tags are applicable for subscriptions, only a user tag can be associated with a subscription.

Add tags to subscription

This API adds one or more tags to a subscription. The tag definition corresponding to the tag to be added must already exist.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/tags

Request Body

A JSON array corresponding to the tag definition IDs to be added.

Query Parameters

None.

Returns

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

Example Request:

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -d '[
            "353752dd-9041-4450-b782-a8bb03a923c8"
        ]' \
  'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags'

Retrieve subscription tags

Retrieve all tags attached to this subscription.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/tags

Query Parameters

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

Response

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

Example Request:

curl \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags'

Example Response:

[
  {
    "tagId":"d0513754-56a9-4694-abb1-3ac46c72e861",
    "objectType":"SUBSCRIPTION",
    "objectId":"77e23878-8b9d-403b-bf31-93003e125712",
    "tagDefinitionId":"353752dd-9041-4450-b782-a8bb03a923c8",
    "tagDefinitionName":"foo",
    "auditLogs":[]
  }
]

Remove tags from subscription

This API deletes one or more tags attached to a subscription.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/tags

Query Parameters

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

Response

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

Example Request:

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "X-Killbill-CreatedBy: demo" \
    'http://127.0.0.1:8080/1.0/kb/subscriptions/77e23878-8b9d-403b-bf31-93003e125712/tags?tagDef=353752dd-9041-4450-b782-a8bb03a923c8'

Audit Logs

Audit logs provide a record of events that occur involving various specific resources. For details on audit logs see Audit and History.

Retrieve subscription audit logs with history by subscription id

Retrieve a list of audit log records showing changes to the subscription. History information (a copy of the full subscription object) is included with each record.

Some examples:

  • Assuming the API is invoked after an IN_ADVANCE subscription is created, it would return two records:
    • An INSERT record corresponding to the subscription creation
    • An UPDATE record corresponding to the chargedThroughDate update
  • Assuming the API is invoked after a plan change, it would return three records:
    • An INSERT record corresponding to the subscription creation
    • An UPDATE record corresponding to the chargedThroughDate update
    • An UPDATE record corresponding to plan change

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/{subscriptionId}/auditLogsWithHistory

Query Parameters

None.

Response

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

Example Request:

curl -v \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/subscriptions/70b6856e-6938-495f-9ae9-0a8ec0571c37/auditLogsWithHistory"

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION",
    "objectId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": "2019-02-22T22:38:10.000Z",
      "recordId": 465,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "bundleId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "category": "BASE",
      "startDate": "2019-02-22T22:38:10.000Z",
      "bundleStartDate": "2019-02-22T22:38:10.000Z",
      "chargedThroughDate": null,
      "migrated": false,
      "tableName": "SUBSCRIPTIONS",
      "historyTableName": "SUBSCRIPTION_HISTORY"
    }
  },
  {
    "changeType": "UPDATE",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION",
    "objectId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
    "changedBy": "SubscriptionBaseTransition",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": "2019-02-22T22:38:10.000Z",
      "recordId": 465,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "bundleId": "d1b329c7-7dcf-466c-aaca-47bff304dab0",
      "category": "BASE",
      "startDate": "2019-02-22T22:38:10.000Z",
      "bundleStartDate": "2019-02-22T22:38:10.000Z",
      "chargedThroughDate": "2019-03-22T23:35:14.000Z",
      "migrated": false,
      "tableName": "SUBSCRIPTIONS",
      "historyTableName": "SUBSCRIPTION_HISTORY"
    }
  }
]

Retrieve subscription event audit logs with history by subscription event id

Retrieve a list of audit log records showing changes to a subscription event. History information (a copy of the full subscription event object) is included with each record. The subscription resource contains the list of events associated with a subscription and the event id can be obtained from here.

Some examples:

  • If a cancel request is issued for a subscription, this API can be invoked with the subscription event id of the CANCEL event. In this case, it will return:
    • An INSERT record corresponding to the subscription cancel event creation
  • If a subscription is future cancelled and then uncancelled, and this API is invoked with the id of the CANCELevent, it will return two records:
    • An INSERT record corresponding to the CANCEL event creation
    • A DELETE record corresponding to the CANCEL event deletion.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/subscriptions/events/{subscriptionEventId}/auditLogsWithHistory

Query Parameters

None.

Response

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

Example Request:

curl  \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/subscriptions/events/9a1c85d5-beba-40c8-9268-f73e09c24007/auditLogsWithHistory"

Example Response:

[
  {
    "changeType": "INSERT",
    "changeDate": "2019-02-22T22:38:10.000Z",
    "objectType": "SUBSCRIPTION_EVENT",
    "objectId": "9a1c85d5-beba-40c8-9268-f73e09c24007",
    "changedBy": "admin",
    "reasonCode": null,
    "comments": null,
    "userToken": "1f03e074-dea1-45c5-aee3-c9464886f476",
    "history": {
      "id": null,
      "createdDate": "2019-02-22T22:38:10.000Z",
      "updatedDate": "2019-02-22T22:38:10.000Z",
      "recordId": 1358,
      "accountRecordId": 10,
      "tenantRecordId": 1,
      "totalOrdering": 0,
      "eventType": "API_USER",
      "userType": "CREATE",
      "effectiveDate": "2019-02-22T22:38:10.000Z",
      "subscriptionId": "70b6856e-6938-495f-9ae9-0a8ec0571c37",
      "planName": "foo-monthly",
      "phaseName": "foo-monthly-evergreen",
      "priceListName": "DEFAULT",
      "billingCycleDayLocal": 0,
      "isActive": true,
      "tableName": "SUBSCRIPTION_EVENTS",
      "historyTableName": "SUBSCRIPTION_EVENT_HISTORY",
      "active": true
    }
  }
]