Subscription Upgrade System Addendum A: Dynamic Upgrades


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.

Regional Pricing Support

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:

Dynamic 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:

DescriptionExample Value
upgradeTypeIdThe 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
specialOfferIndicates 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
prorateThis 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
sharedAuthenticationIndicates 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
formNameThe 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:

DescriptionExample Value
regionalPricingIdThe 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.

Code Examples

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.

Encryption Method

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:<strong>&upgradeClientSubacc=0001&upgradeClientAccnum=900000&upgradeTypeId=4530&regionalPricingId=443</strong>

Alternately, the request can be made using hidden HTML form fields, as shown in the next example:

<form method="POST"<br>action=""><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>

Background HTTPS Post Method

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:

The values can also be passed using an HTML form

<form method="POST" 
<input type="hidden" name="clientAccnum" value="900000">
<input type="hidden" name="clientSubacc" value="0000">
<input type="hidden" name="action" value=" allowUpgrade">

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:

The values can also be passed using an HTML form:

<form method="POST"
<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>

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:

  • originalClientAccnum. The six-digit Merchant account number from where the upgrade originated.
  • originalClientSubacc. The four-digit Merchant subaccount number from where the upgrade originated.
  • originalSubscriptionId. The subscription ID number of the original subscription.

For more information on the use of Background Post, please consult the CCBill Background Post User’s Guide.