CCBill API: Direct Discount API
Introduction
This document is issued as an addendum to the CCBill API documentation and discusses subscription discounting functionality. This document is written for developers, technicians, and others with advanced coding skills.Overview
CCBill has added calls to the CCBill API that allow users to discount subscriptions as an additional tool for consumer retention. The same functionality has been added to the CCBill Admin Portal for those who cannot access the system via the API.Exclusions
Parameters that are always required (such as clientAccnum, username, password, etc.) are excluded from this chart and are discussed in the main CCBill API.discountSubscription
The discountSubscription call allows you to discount the subscription by a set amount or an entirely new recurring price, depending on the parameters sent with the call.Discount by Amount
Required (X) and Optional (O) Parameters
discountSubscription | clientSubacc | usingSubacc | subscriptionId | returnXML | dicsountAmount |
---|---|---|---|---|---|
Main Account | O |
O |
X |
X |
|
Main Account w/XML | O |
O |
X |
X |
X |
Subaccount | O |
O |
X |
X |
|
Subaccount w/XML | O |
O |
X |
X |
X |
CSV VERSION EXAMPLE
Request Stringhttps://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900112&clientSubacc=0000&username=yourUsername&password=yourPassword&discountAmount=2.00&action=discountSubscription&subscriptionId=1113346401000000080
Response
"results" "-10"
XML VERSION EXAMPLE
Request Stringhttps://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900112&clientSubacc=0000&username=yourUsername&password=yourPassword&discountAmount=2.00&action=discountSubscription&subscriptionId=1113346401000000080&returnXML=1
Response
<?xml version="1.0" standalone="true"?> <results>-10</results>
Set New Recurring Price
discountSubscription | clientSubacc | usingSubacc | subscriptionId | returnXML | newRecurringPrice |
---|---|---|---|---|---|
Main Account | O |
O |
X |
X |
|
Main Account w/XML | O |
O |
X |
X |
X |
Subaccount | O |
O |
X |
X |
|
Subaccount w/XML | O |
O |
X |
X |
X |
CSV VERSION EXAMPLE
Request Stringhttps://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900112&clientSubacc=0000&username=yourUsername&password=yourPassword&newRecurringPrice=18.95&action=discountSubscription&subscriptionId=1113346401000000080
Response
"results" "-10"
XML VERSION EXAMPLE
Request Stringhttps://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900112&clientSubacc=0000&username=yourUsername&password=yourPassword&newRecurringPrice=18.95&action=discountSubscription&subscriptionId=1113346401000000080&returnXML=1
Response
<?xml version="1.0" standalone="true"?> <results>-10</results>
Information Returned
Error Codes
Code | Description | More Information |
---|---|---|
-2 | The subscription ID provided was invalid or the subscription type is not supported by the requested action. | A new recurring price cannot be passed in for a non-recurring subscription. |
-18 | Recurring price is less than the minimum allowable. | A discount cannot be added to any subscription that will result in a price lower than 5.00 units (currency notwithstanding). |
-19 | Discount amount is less than the minimum allowable. | The discount amount cannot be less than 0.01 units (currency notwithstanding). |
-20 | The New recurring price is greater than the subscription recurring price. | The system cannot process a discount that results in a higher price than the current subscription. |
-21 | Cannot replace cancel discount with a smaller amount. | The system cannot process a discount with this function that DOES NOT result in a lower subscription price than an already existing cancel discount. |
-22 | This subscription is not eliigible for a discount. | Discounts can only be applied to an Active trial or an Active recurring subscription. |
Version History
Version | Date | Change Log |
---|---|---|
1 | 1.16.2014 | New CCBill API Call Documentation. |