Sign up

Upgrade Licenses

Upgrade licenses let your existing customers transition from their current version or edition to a newer one. A user with My Product Standard can upgrade to My Product Gold, or a user on V1 can upgrade to V2.

The upgrade process involves two serial numbers: the source (current license) and the target (upgrade license). The KEYZY server validates the upgrade path, deletes the source license, and makes the target available for activation.

Prerequisites

Setup

Create the activator and obtain the validator:

#include "KeyzyLicenseActivator.h"

Keyzy::ProductData productData(
    "YOUR_APP_ID",
    "YOUR_API_KEY",
    "YOUR_PRODUCT_CODE",
    "YOUR_CRYPTION_KEY"
);

std::unique_ptr<Keyzy::KeyzyLicenseActivator> pActivator =
    std::make_unique<Keyzy::KeyzyLicenseActivator>(productData);

std::shared_ptr<Keyzy::KeyzyLicenseValidator> pValidator =
    pActivator->getLicenseValidator();

If the user’s current license is already activated on the device, the source serial is stored locally. You only need to provide the target (upgrade) serial:

std::string targetSerial = "TARG-ETSE-RIAL-XXXX"; // the upgrade serial

Keyzy::LicenseStatus status = pActivator->upgradeLicense(targetSerial);

if (status == Keyzy::LicenseStatus::VALID)
{
    // Upgrade successful on the server — now activate the target serial
    status = pActivator->activateSemiOnline(targetSerial);
}
else
{
    // Upgrade failed
}

Upgrade with Explicit Serials

If you need to provide both serials explicitly (e.g. the source serial is not stored on the device), use the two-parameter overload:

std::string sourceSerial = "SOUR-CESE-RIAL-XXXX"; // current license
std::string targetSerial = "TARG-ETSE-RIAL-XXXX"; // upgrade license

Keyzy::LicenseStatus status = pActivator->upgradeLicense(sourceSerial, targetSerial);

if (status == Keyzy::LicenseStatus::VALID)
{
    // Upgrade successful on the server — now activate the target serial
    status = pActivator->activateSemiOnline(targetSerial);
}
else
{
    // Upgrade failed
}

Important: Activate After Upgrade

The upgradeLicense() method only performs the upgrade on the KEYZY server. It does not activate the new license or store the target serial on the device. After a successful upgrade, you must call one of the activation methods to activate the target serial:

// Choose the activation schema that matches your setup
pActivator->activateSemiOnline(targetSerial);  // or
pActivator->activateOnline(targetSerial);      // or
pActivator->activateOffline(licenseFilePath);

Choosing the Path Up Front

Before showing the upgrade form, check whether a license is already active on the device and choose the UI path accordingly. Call validateOnline() on the validator — it takes no serial (it uses the serial already stored on the device) and only reads the status; it does not activate anything.

        Upgrade starts
              │
        validateOnline()
              │
      ┌───────┴───────────────────────┐
    VALID                          not VALID
 (license on device)     (CLIENT_SERIAL_DOES_NOT_EXIST)
      │                                │
  1 field:                         2 fields:
  target serial                    source + target serial
      │                                │
 upgradeLicense(target)     upgradeLicense(source, target)
      └────────────────┬───────────────┘
                       │
       activate (activateOnline / activateSemiOnline)
                       │
                unlock new version

The example below follows the diagram end to end:

// Upgrade starts — first check what is already on the device,
// without asking the user for anything yet.
Keyzy::LicenseStatus status = pValidator->validateOnline();

std::string targetSerial;

if (status == Keyzy::LicenseStatus::VALID)
{
    // A license is already active — show a single field for the upgrade (target) serial
    targetSerial = getTargetSerialFromUser();
    status = pActivator->upgradeLicense(targetSerial);
}
else // CLIENT_SERIAL_DOES_NOT_EXIST — no license on this device
{
    // Show two fields: the current (source) serial and the upgrade (target) serial
    std::string sourceSerial = getSourceSerialFromUser();
    targetSerial = getTargetSerialFromUser();
    status = pActivator->upgradeLicense(sourceSerial, targetSerial);
}

// Both paths converge — activate the target serial after the upgrade
if (status == Keyzy::LicenseStatus::VALID)
{
    status = pActivator->activateOnline(targetSerial); // or activateSemiOnline

    if (status == Keyzy::LicenseStatus::VALID)
    {
        // Upgrade complete — unlock the new version/edition
    }
}

WooCommerce Integration

If you are using the KEYZY WooCommerce plugin, your customers can perform the upgrade directly from your store. The plugin provides an upgrade form where the user enters both serial numbers, and the upgrade is handled automatically on the server side.

Error Handling

The most common LicenseStatus values for upgrade operations are UPGRADE_LICENSE_DOES_NOT_MATCH, UPGRADE_LICENSE_DOES_NOT_EXIST, CURRENT_LICENSE_DOES_NOT_EXIST, and CLIENT_SERIAL_DOES_NOT_EXIST.

For the complete list of all status codes and their descriptions, see the C++ License Status Codes reference.

Next Steps