Skip to main content

Build custom upgrade links


On-demand upgrade links allow you to create your own rules in terms of product upgrades, overriding existing upgrade settings through URL parameters.

Custom upgrade links allow you to define:

  • The upgrade product
  • Upgrade price
  • Product quantity
  • Pricing options
  • Time interval to replace subscription lifetime  

Build your upgrade links using the following parameters.

Parameter Required / Optional Type/Description
LICENSE Required

Specifies the subscription to be upgraded.

PROD Required Product ID of the target product used in the upgrade process.
PRICES(ProductId)[CURRENCY] Required

Price and currency to be used in the custom upgrade process.

Example: PRICES4692644[USD]=999
QTY Optional

Set product quantity. It does not impact the total order price.


PERIOD Optional Period of time to replace the subscription lifetime. Starts when the order is finalized. Requires PRICES parameter.
OPTIONS(ProductID) Optional

Product pricing options to be applied to the upgrade product.

Example: OPTIONS4692644=option1,option2
PHASH Required if using PRICE, PERIOD, OPTIONS, and/or QTY HMAC_MD5 signature in order to prevent the request from being exploited. All custom upgrade links require digital signing, similar to current manual renewal links.

Upgrade a subscription with a specific price and period of time

For this example, let's assume that we need a custom on-demand upgrade link for Subscription A (monthly subscription expiring on June 30th, 2019 with the reference ABC1D2E345) associated with Product A with the ID 1234567.

Product A is offered to customers in two versions:

  • 1 user (code: 1user) - $99.99; (the customer using Subscription A opted for this particular pricing option).
  • 2 users (code: 2users) - $149.99.

You're looking to prolong the subscription lifetime with 30 days, and charge the customer $50. For this example, the parameters must have the following values:

  • PROD=1234567
  • OPTIONS1234567=1user
  • PRICES1234567[USD]=50
  • QTY=4
  • PERIOD=30

The resulting upgrade link (excluding PHASH) is:[USD]=50&QTY=4&PERIOD=30

Secure upgrade links

Use a HMAC_MD5 signature to prevent links from being exploited. To calculate the HMAC_MD5 signature, you need to build a string from the query parameters of the Buy Link prefixed by the length of the sequence of parameters in tandem with the 2Checkout-generated SECRET KEY for your account (view secret key). 

  1. Using the parameters above, you get the following sequence: 
  2. You need to add the length of the character sequence at its beginning, to calculate the hash, namely 90. The resulting base string is
  3. For the purpose of this demo, let's assume that your secret key is SECRET_KEY.
  4. Use the secret key and the base string to calculate the HMAC-MD5 HASH. The result should be: 54e7d22d741f3ceacfe80586ba5d55a7 (valid exclusively for this example).
  5. The final upgrade link:[USD]=50&QTY=4&PERIOD=30&PHASH=54e7d22d741f3ceacfe80586ba5d55a7
  • Was this article helpful?