This guide is issued as an addendum to the Subscription Upgrade System documentation and discusses dynamic upgrade functionality. It is intended for developers, technicians, and others with advanced coding skills.
This guide should be used in conjunction with the Subscription Upgrade System User’s Guide. References to the User’s Guide will be made when appropriate.
Dynamic upgrades, also referred to as pass-through upgrades, allow Merchants to upgrade a consumer subscription to a new subscription without pre-configuring an option in the system. The upgrade can be made to the same sub-account or a different sub-account, and can be hard-coded on a page or created dynamically using a script. Dynamic upgrades are set up entirely by the Merchant but use CCBill’s form system. In order to use Dynamic Upgrades, the Merchant must contact Merchant Support and request the feature be enabled.
Dynamic Upgrades support the use of Regional Pricing. By default, the Regional Pricing settings of the account to which the subscription is being upgraded will be used. Optionally, a Regional Pricing profile other than the default for the upgraded account can be applied, as explained below. This setting will be ignored if Regional Pricing is not enabled on the account. For more information on Regional Pricing, please consult the Regional Pricing User’s Guide.
The system supports both Credit Card and ACH (Automated Clearing House) upgrades.
Dynamic upgrades are created by passing variables into a query string. Requests should be sent to the following CGI script with variable values appended:
https://bill.ccbill.com/jpost/upgradeSubscription.cgiDynamic upgrades will be completed as though they were previously set up in the system. Once the variables have been passed to the above CGI script, the consumer will be redirected to the upgrade form.
To create the upgrade, simply create a price point in the Pricing Area of the CCBill Admin Portal. For help creating price points, please visit the Price Points help page.
As explained in the Subscription Upgrade User’s Guide, two upgrade methods are available: Encryption and Background HTTPS Post. The values required for dynamic upgrades should be included along with the variables listed in the User’s Guide for the desired method. Note that the upgradeTypeId variable is included in both guides, but is obtained in a different manner than regular (non-dynamic) upgrades.
The following variable values must be passed into the string:
| Variable Name | Description | Example Value |
|---|---|---|
| upgradeTypeId | The unique identifier for the price point to which the subscription will be upgraded. This value can be obtained in the Pricing Admin section of the CCBill Admin Portal. | 4530 |
| specialOffer | Indicates whether the upgrade is a special offer. A value of zero (0) signifies the upgrade is not a special offer and will cancel the original subscription. A value of one (1) indicates a special offer and will not cancel the original subscription. | 0 or 1 |
| prorate | This value indicates the preferred prorate option. A value of one (1) prorates the amount and a value of two (2) prorates the length of time. | 1 or 2 |
| sharedAuthentication | Indicates whether shared authentication is used; a value of one (1) signifies shared authentication is used and a value of zero (0) signifies that shared authentication is not used. | 0 or 1 |
| formName | The name of the CCBill form used to perform the upgrade. This value is optional; if no parameter is specified, the default upgrade form will be used. | 1ug |
Note: If specialOffer is set to zero (0), the prorate parameter must be included. Otherwise, the prorate parameter is not used.
If you wish to specify a particular Regional Pricing setting, you may optionally pass in the following variable:
| Variable Name | Description | Example Value |
|---|---|---|
| regionalPricingId | The unique identifier for the Regional Pricing setting you wish to use for the upgraded account. This value will be ignored if Regional Pricing is not enabled on the account. | 443 |
The value for regionalPricingId can be obtained by contacting Merchant Support.
As mentioned in the Subscription Upgrade System User’s Guide, two methods are available for transmitting upgrade requests: Encryption and Backend HTTPS Post (consult the User’s Guide for details on these two methods). For each type, parameters can be passed through the URL or by using hidden HTML form fields. Some parameters are optional, as noted in the User’s Guide. Each of the following code examples shows optional parameters as bold text.
If using the Encryption method, pass the above variables in the upgrade request string in addition to those specified in the User’s Guide. The following URL demonstrates an example of a dynamic upgrade request:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSubacc=0000&enc=jas2jasdfbJBD19823naISDHASDoiksj923&subscriptionId=0208224109000000496<strong>&upgradeClientSubacc=0001&upgradeClientAccnum=900000&upgradeTypeId=4530®ionalPricingId=443</strong>Alternately, the request can be made using hidden HTML form fields, as shown in the next example:
<form method="POST"<br>action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi"><br><input type="hidden" name="clientAccnum" value="900000"><br><input type="hidden" name="clientSubacc" value="0000"><br><input type="hidden" name="enc" value=" jas2jasdfbJBDA9823naISDHdSDoiksj923"><br><input type="hidden" name="subscriptionId" value="1234567890"><br><input type="submit" name="submit" value="UpgradeSubscription"><br><strong><input type="hidden" name="upgradeClientAccnum" value="900000"><br><input type="hidden" name="upgradeClientSubacc" value="0001"><br><input type="hidden" name="upgradeTypeId" value="40530"><br><input type="hidden" name="regionalPricingId" value="443"></strong><br></form>If using the Background HTTPS Post method, dynamic upgrade variables should be passed in during step two.
The following code example demonstrates step one of the Backend HTTPS Post using dynamic upgrades:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSubacc=0000&action=allowUpgrade&subscriptionId=0208724102000000496The values can also be passed using an HTML form
<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900000">
<input type="hidden" name="clientSubacc" value="0000">
<input type="hidden" name="action" value=" allowUpgrade">
</form>The string will return a numeric value. A value of "1" means the request is approved (see the User’s Guide for a complete list of return values). The following example represents code that can be used for step two of the process:
https://bill.ccbill.com/jpost/upgradeSubscription.cgi?clientAccnum=900000&clientSubacc=0000&action=upgradeSubscription&subscriptionId=0208224109000000496&upgradeClientSubacc=0001&upgradeClientAccnum=900000&upgradeTypeId=40530®ionalPricingId=443
The values can also be passed using an HTML form:
<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900000">
<input type="hidden" name="clientSubacc" value="0000">
<input type="hidden" name="action" value=" upgradeSubscription">
<input type="hidden" name="subscriptionId" value="1234567890">
<input type="submit" name="submit" value="Upgrade Subscription">
<strong><input type="hidden" name="upgradeClientAccnum" value="900000">
<input type="hidden" name="upgradeClientSubacc" value="0001">
<input type="hidden" name="upgradeTypeId" value="40530">
<input type="hidden" name="regionalPricingId" value="443"></strong>
</form>HTML form examples show a button which, when clicked, will pass the parameters into the Subscription Upgrade system. If successful, the upgrade will be performed.
Variable values are posted back using the CCBill Background Post system. The following values will be sent to the Approval URL or Denial URL when the upgrade has been performed or denied, respectively:
For more information on the use of Background Post, please consult the CCBill Background Post User’s Guide.