License Key Upgrades

You can provide software license key upgrades at discounted prices. You can choose to authenticate customers’ credentials for these offers.

There are different ways to authenticate customer credentials before granting access to a purchase at a discounted price. The most common method is to send the customers an email with an upgrade purchase link.

An alternative method uses an API to validate the customer’s eligibility for the upgrade purchase. There are three steps in the API method:

Step 1: Set Up License Key Upgrades in Commerce Assistant

1. In Commerce Assistant, in the Setup menu, select Account Setup.
2. Click the Upgrade Management section to set up your upgrade information. This section is used to configure the API settings used for validating a customer's eligibility for software license key upgrades.
3. Enter the following settings:

Step 2: Checkout Process for License Key Upgrades

When the API is configured, the customer is asked to provide the existing license key next to the respective item in the shopping cart.

You decide which products will require customers to enter previous license keys. Contact Client Experience to set up this option.

The customer is prevented from continuing the order process until a valid license key is provided.

Step 3: Validation of License Key Upgrades

The license key for the upgrade must be validated by your web server:

Validation Call

The customer submits the previous license key for validation to your web server.

Cleverbridge sends an HTTP POST request for an XML document to the URL you defined.

The XML document submitted in the POST follows an XSD definition available at:

http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd

📘

Note

This link may be different depending on which XML schema you use.

The following shows a sample XML document according to this definition:

<?xml version="1.0" encoding="utf-8"?>
<cbn:ValidatePreviousLicenseCartItemRequest xmlns:cbn="http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd">
  <cbn:CustomerInformation cbt:Id="NEW" xmlns:cbt="http://xml.cleverbridge.com/3.500/cleverbridgeTypes.xsd">
    <cbt:LanguageId>de</cbt:LanguageId>
  </cbn:CustomerInformation>
  <cbn:Item cbt:RunningNo="1" xmlns:cbt="http://xml.cleverbridge.com/3.500/cleverbridgeTypes.xsd">
    <cbt:ProductId>12345</cbt:ProductId>
    <cbt:ProductName>The Product Name</cbt:ProductName>
    <cbt:YourProductId>123AB</cbt:YourProductId>
    <cbt:ProductReportingGroup>Example Product Group</cbt:ProductReportingGroup>
    <cbt:ClientId>864</cbt:ClientId>
    <cbt:Quantity>2</cbt:Quantity>
    <cbt:PreviousLicense>12345</cbt:PreviousLicense>
    <cbt:YourCurrency>Euro</cbt:YourCurrency>
    <cbt:YourCurrencyId>EUR</cbt:YourCurrencyId>
  </cbn:Item>
</cbn:ValidatePreviousLicenseCartItemRequest>

Validation Response

Your license validation server must respond with an HTTP status of 200 (OK) regardless if the entered key is valid or not. Any other HTTP status is treated as an error and causes the validation process to fail.

The response must be formatted as described in the following URL:

`http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd'

📘

Note

This link may be different depending on which XML schema you use.

The following is a sample of a formatted response:

<?xml version="1.0" encoding="UTF-8"?>
<cbn:ValidatePreviousLicenseCartItemResponse xmlns:cbn="http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd">
  <cbn:Valid>false</cbn:Valid>
  <cbn:ErrorId>KNF</cbn:ErrorId>
</cbn:ValidatePreviousLicenseCartItemResponse>

The following are responses showing various return values:

• All OK

<?xml version="1.0" encoding="UTF-8"?>
<cbn:ValidatePreviousLicenseCartItemResponse xmlns:cbn="http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd">
  <cbn:Valid>true</cbn:Valid>
</cbn:ValidatePreviousLicenseCartItemResponse>

• Key Expired

<?xml version="1.0" encoding="UTF-8"?>
<cbn:ValidatePreviousLicenseCartItemResponse xmlns:cbn="http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd">
  <cbn:Valid>false</cbn:Valid>
  <cbn:ErrorId>KEP</cbn:ErrorId>
</cbn:ValidatePreviousLicenseCartItemResponse>

• Custom Error Message

<?xml version="1.0" encoding="UTF-8"?>
<cbn:ValidatePreviousLicenseCartItemResponse xmlns:cbn="http://xml.cleverbridge.com/3.500/cleverbridgeUpgradeManagement.xsd">
  <cbn:Valid>false</cbn:Valid>
  <cbn:ErrorId>CUS</cbn:ErrorId>
  <cbn:Text>Custom Error Text</cbn:Text>
</cbn:ValidatePreviousLicenseCartItemResponse>

When validating keys, Cleverbridge waits up to 10 seconds before it considers the validation attempt failed. The validation is also considered to have failed if the server responds with an HTTP status other than 200 or if the returned XML document is invalid.

Cleverbridge can configure what happens in case of a failed validation attempt. For example, Cleverbridge can accept the upgrade or reject it.

Cleverbridge tries to minimize the number of calls to the validation servers. An additional call is not made when the license quantity is changed for a cart item that has previously been validated. For that reason you are requested to always return the minimum and maximum number of upgrade licenses that can be purchased based on a validated key.

Once the license key is successfully validated, the customer is able to continue.

🚧

Important

Cleverbridge does not encourage you to use this process unless it is considered absolutely necessary. Requiring a customer to enter a previous key during the order process is an additional hurdle for the customer in order to submit the upgrade order. This can have a negative impact on conversion rates and decrease overall revenue.

Sample Code for License Key Upgrades

There are two pieces of sample code that Cleverbridge can provide. You can extend them to make them work with your license database.

• PHP sample code (PreviousLicense.php)
• C# sample project (ValidatePreviousLicenseDemo.zip)