Working with Subscriptions in Kill Bill

Overview

The following operations allow you to work with Subscriptions. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with subscriptions, see Sample configuration.

Operation	Description
createSubscription	Creates a subscription.
updateSubscription	Updates a subscription.
deleteSubscription	Deletes a subscription.
getSubscriptionById	Retrieve a subscription by id.

Operation details

This section provides further details on the operations related to subscriptions.

Creating a subscription

The createSubscription operation creates a subscription.

createSubscription

<killbill.createSubscription>
    <accountId>{$ctx:accountId}</accountId>
    <externalKey>{$ctx:externalKey}</externalKey>
    <bundleId>{$ctx:bundleId}</bundleId>
    <subscriptionId>{$ctx:subscriptionId}</subscriptionId>
    <startDate>{$ctx:startDate}</startDate>
    <productName>{$ctx:productName}</productName>
    <productCategory>{$ctx:productCategory}</productCategory>
    <billingPeriod>{$ctx:billingPeriod}</billingPeriod>
    <phaseType>{$ctx:phaseType}</phaseType>
    <priceList>{$ctx:priceList}</priceList>
    <sourceType>{$ctx:sourceType}</sourceType>
    <cancelledDate>{$ctx:cancelledDate}</cancelledDate>
    <chargedThroughDate>{$ctx:chargedThroughDate}</chargedThroughDate>
    <billingStartDate>{$ctx:billingStartDate}</billingStartDate>
    <state>{$ctx:state}</state>
    <billingEndDate>{$ctx:billingEndDate}</billingEndDate>
    <events>{$ctx:events}</events>
    <priceOverrides>{$ctx:priceOverrides}</priceOverrides>
    <requestedDate>{$ctx:requestedDate}</requestedDate>
    <callCompletion>{$ctx:callCompletion}</callCompletion>
    <callTimeoutSec>{$ctx:callTimeoutSec}</callTimeoutSec>
    <pluginProperty>{$ctx:pluginProperty}</pluginProperty>
    <auditLogs>{$ctx:auditLogs}</auditLogs>
    <createdBy>{$ctx:createdBy}</createdBy>
    <reason>{$ctx:reason}</reason>
    <comment>{$ctx:comment}</comment>
</killbill.createSubscription>

Properties

accountId: The id of the account.
externalKey: The external key for the subscription.
bundleId: The bundle id for the subscription.
subscriptionId: The id for the subscription.
startDate: The start date for the subscription.
productName: The product name for the subscription.
productCategory: The product category for the subscription.
billingPeriod: The billing period for the subscription.
phaseType: The phase type for the subscription.
priceList: The price list for the subscription.
sourceType: The source type for the subscription.
cancelledDate: The cancel date for the subscription.
chargedThroughDate: The charged through date for the subscription.
billingStartDate: The billing start date for the subscription.
state: The state for the subscription.
billingEndDate: The billing end date for the subscription..
events: The events for the subscription.
priceOverrides: The price overrides for the subscription.
requestedDate: The requested date for the subscription.
callCompletion: The call completion for the subscription call.
callTimeoutSec: The call timeout sec for this subscription call.
pluginProperty: The plugin property for the subscription.
auditLogs: The audit logs for the subscription.
createdBy: The creator of this subscription call.
reason: The reason for the creation of subscription.
comment: The comment for the creation of subscription.

Sample request

Following is a sample REST/JSON request that can be handled by the createSubscription operation.

Sample Request for createSubscription

{
    "apiUrl":"http://127.0.0.1:8080",
    "apiVersion":"1.0",
    "username":"admin",
    "password":"password",
    "apiKey":"bob",
    "apiSecret":"lazar",
    "accountId": "33ca98be-2e86-4861-89df-31cd1f7207ef",
    "externalKey": "myBundleName",
    "productName": "Standard",
    "productCategory": "BASE",
    "billingPeriod": "MONTHLY",
    "priceList": "DEFAULT",
    "createdBy":"demo"
}

Note

There are optional parameters available. For more information on the usage of these parameters please check the API document.

Modifying a subscription

The updateSubscription operation retrieves a single subscription.

updateSubscription

<killbill.updateSubscription>
    <accountId>{$ctx:accountId}</accountId>
    <externalKey>{$ctx:externalKey}</externalKey>
    <bundleId>{$ctx:bundleId}</bundleId>
    <subscriptionId>{$ctx:subscriptionId}</subscriptionId>
    <startDate>{$ctx:startDate}</startDate>
    <productName>{$ctx:productName}</productName>
    <productCategory>{$ctx:productCategory}</productCategory>
    <billingPeriod>{$ctx:billingPeriod}</billingPeriod>
    <phaseType>{$ctx:phaseType}</phaseType>
    <priceList>{$ctx:priceList}</priceList>
    <sourceType>{$ctx:sourceType}</sourceType>
    <cancelledDate>{$ctx:cancelledDate}</cancelledDate>
    <chargedThroughDate>{$ctx:chargedThroughDate}</chargedThroughDate>
    <billingStartDate>{$ctx:billingStartDate}</billingStartDate>
    <state>{$ctx:state}</state>
    <billingEndDate>{$ctx:billingEndDate}</billingEndDate>
    <events>{$ctx:events}</events>
    <priceOverrides>{$ctx:priceOverrides}</priceOverrides>
    <requestedDate>{$ctx:requestedDate}</requestedDate>
    <callCompletion>{$ctx:callCompletion}</callCompletion>
    <callTimeoutSec>{$ctx:callTimeoutSec}</callTimeoutSec>
    <pluginProperty>{$ctx:pluginProperty}</pluginProperty>
    <auditLogs>{$ctx:auditLogs}</auditLogs>
    <createdBy>{$ctx:createdBy}</createdBy>
    <reason>{$ctx:reason}</reason>
    <comment>{$ctx:comment}</comment>
</killbill.updateSubscription>

Properties

accountId: The id of the account.
externalKey: The external key for the subscription.
bundleId: The bundle id for the subscription.
subscriptionId: The id for the subscription.
startDate: The start date for the subscription.
productName: The product name for the subscription.
productCategory: The product category for the subscription.
billingPeriod: The billing period for the subscription.
phaseType: The phase type for the subscription.
priceList: The price list for the subscription.
sourceType: The source type for the subscription.
cancelledDate: The cancel date for the subscription.
chargedThroughDate: The charged through date for the subscription.
billingStartDate: The billing start date for the subscription.
state: The state for the subscription.
billingEndDate: The billing end date for the subscription.
events: The events for the subscription.
priceOverrides: The price overrides for the subscription.
requestedDate: The requested date for the subscription.
callCompletion: The call completion for the subscription call.
callTimeoutSec: The call timeout sec for the subscription call.
pluginProperty: The plugin property for the subscription.
auditLogs: The audit logs for the subscription.
createdBy: The creator of this subscription call.
reason: The reason for updating the subscription.
comment: The comment for the updation of subscription.

Sample request

Following is a sample REST/JSON request that can be handled by the updateSubscription operation.

Sample Request for updateSubscription

{
    "apiUrl":"http://127.0.0.1:8080",
    "apiVersion":"1.0",
    "username":"admin",
    "password":"password",
    "apiKey":"bob",
    "apiSecret":"lazar",
    "subscriptionId": "33cde8be-2e86-4961-89df-31cdkf94207ef",
    "productName": "Standard",
    "productCategory": "BASE",
    "billingPeriod": "MONTHLY",
    "priceList": "DEFAULT",
    "createdBy":"demo"
}

Note

There are optional parameters available. For more information on the usage of these parameters please check the API document.

Deleting a Subscription

The deleteSubscription operation deletes a subscription specified by the id.

deleteSubscription

<killbill.deleteSubscription>
    <subscriptionId>{$ctx:subscriptionId}</subscriptionId>
    <requestedDate>{$ctx:requestedDate}</requestedDate>
    <callCompletion>{$ctx:callCompletion}</callCompletion>
    <callTimeoutSec>{$ctx:callTimeoutSec}</callTimeoutSec>
    <pluginProperty>{$ctx:pluginProperty}</pluginProperty>
    <createdBy>{$ctx:createdBy}</createdBy>
    <reason>{$ctx:reason}</reason>
    <comment>{$ctx:comment}</comment>
    <entitlementPolicy>{$ctx:entitlementPolicy}</entitlementPolicy>
    <billingPolicy>{$ctx:billingPolicy}</billingPolicy>
    <useRequestedDateForBilling>{$ctx:useRequestedDateForBilling}</useRequestedDateForBilling>
</killbill.deleteSubscription>

Properties

subscriptionId: The id of the subscription.
requestedDate: The ID of the project to which the story belongs.
callCompletion: The call completion of the subscription call.
callTimeoutSec: The call timeout sec of the subscription call.
entitlementPolicy: The entitlement policy of the subscription.
billingPolicy: The billing policy of the subscription.
useRequestedDateForBilling: The use requested date for billing of the subscription.
pluginProperty: The plugin property of the subscription.
createdBy: The creator of this subscription call.
reason: The reason for deleting the subscription.
comment: The comment for the subscription.

Sample request

Following is a sample REST/JSON request that can be handled by the deleteSubscription operation.

Sample Request for deleteSubscription

{
    "apiUrl":"http://127.0.0.1:8080",
    "apiVersion":"1.0",
    "username":"admin",
    "password":"password",
    "apiKey":"bob",
    "apiSecret":"lazar",
    "subscriptionId": "33ca98be-2e86-4861-89df-31cd1f7207ef",
    "createdBy":"demo"
}

Related Kill Bill documentation

http://killbill.io/api/#!/subscriptions/cancelEntitlementPlan

Retrieving a subscription by the id

The getSubscriptionByIdoperation retrieves a single subscription by the id.

getSubscriptionById

<killbill.getSubscriptionById>
    <subscriptionId>{$ctx:subscriptionId}</subscriptionId>
</killbill.getSubscriptionById>

Properties

subscriptionId: The id of the subscription.

Sample request

Following is a sample REST/JSON request that can be handled by the getSubscriptionById operation.

Sample Request for getSubscriptionById

{
    "apiUrl":"http://127.0.0.1:8080",
    "apiVersion":"1.0",
    "username":"admin",
    "password":"password",
    "apiKey":"bob",
    "apiSecret":"lazar",
    "subscriptionId": "33ca98be-2e86-4861-89df-31cd1f7207ef"
}

Sample configuration

Following is a sample proxy service that illustrates how to connect to Kill Bill with the init operation and use the getSubscriptionByIdoperation. The sample request for this proxy can be found in the getSubscriptionById sample request.

Sample Proxy

<proxy xmlns="http://ws.apache.org/ns/synapse" name="getSubscriptionById" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
   <target>
      <inSequence>
         <property name="apiUrl" expression="json-eval($.apiUrl)"/>
         <property name="username" expression="json-eval($.username)"/>
         <property name="password" expression="json-eval($.password)"/>
         <property name="apiKey" expression="json-eval($.apiKey)"/>
         <property name="apiVersion" expression="json-eval($.apiVersion)"/>
         <property name="apiSecret" expression="json-eval($.apiSecret)"/>
         <property name="blocking" expression="json-eval($.blocking)"/>
         <property name="subscriptionId" expression="json-eval($.subscriptionId)"/>
         <killbill.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <username>{$ctx:username}</username>
            <password>{$ctx:password}</password>
            <apiKey>{$ctx:apiKey}</apiKey>
            <apiSecret>{$ctx:apiSecret}</apiSecret>
            <apiVersion>{$ctx:apiVersion}</apiVersion>
            <blocking>{$ctx:blocking}</blocking>
         </killbill.init>
         <killbill.getSubscriptionById>
             <subscriptionId>{$ctx:subscriptionId}</subscriptionId>
         </killbill.getSubscriptionById>
         <respond />
      </inSequence>
      <outSequence>
         <send />
      </outSequence>
   </target>
   <description />
</proxy>