Custom upgrade links
Overview
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 upgraded product
Upgrade price
Product quantity
Pricing options
Time interval to replace subscription lifetime
Availability
All 2Checkout accounts.
Create the upgrade link
To build upgrade links, you need the following two elements:
The main upgrade link
The unique subscription identifier from the 2Checkout system: LICENSE=ABC1D2E345. The simplest upgrade link you can build is:
Query parameters
Build your upgrade links using the following parameters.
LICENSE
Required
Specifies the subscription to be upgraded.
Example: https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345
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.
PHASH
Required if using PRICE, PERIOD
HMAC_SHA signature in order to prevent the request from being exploited. All custom upgrade links require digital signing, similar to current manual renewal links.
LANG
Optional
ISO country code of the language used for the order processing interface and shopper emails. Default value: EN.
CURRENCY
Optional
Preselects the billing currency to be used in the transaction.
SHOPURL
Optional
Custom URL used for "Back to shopping" link.
OPTIONS(ProductID)
Optional
Preselects the pricing options for the subscription, using the pricing options codes (the IDs you set for each option individually). Append the unique product identifier generated by the 2Checkout platform after the OPTIONS parameter.
Example: OPTIONS1234567=5usr,2year
UPGRADEPROD
Required in conjunction with UPGRADEOPT. Optional otherwise.
Product ID of the target product used in the upgrade process.
UPGRADEOPT
Optional
Product option code of the target product used in the upgrade process. Can only be used in conjunction with UPGRADEPROD.
DESIGN_TYPE
Optional
Use DESIGN_TYPE=1 to change the layout of the shopping cart template interface, positioning the payment methods selector above the billing details area.
LAYOUT_TYPE
Optional
Controls which version of the shopping cart 2Checkout serves. Possible values: CLASSIC (desktop variant) or MOBILE (mobile variant).
REF
Optional
External order reference (string, <100 characters). 2Checkout saves this string at order-level in addition to the system-generated order reference. For longer references, use an sha2/3 hash.
SRC
Optional
Identifies the source of a sale by assigning a unique URL identifier (e.g., SRC=prodpage).
COUPON
Optional
Promotion coupon code(s) applied to the order. Use commas to separate multiple values. Example: &COUPON=voucher1,voucher2
CARD
Optional
Possible values: 1 to display the payment form in the selected landing page (Review page); 2 to display the payment form and place orders immediately after entering payment data (no Review page).
ORDERSTYLE
Optional
Overrides default ordering interface template. Each template in the Interface Templates area has a unique identifier.
AUTO_PREFILL=1
Optional (requires 2Checkout activation)
Use AUTO_PREFILL=1 to set ZIP and country fields as mandatory; address fields may be auto-calculated. Using this parameter without activation falls back to the classic purchase flow where all billing address data is mandatory.
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 by 30 days and charge the customer $50. For this example, the parameters must have the following values:
LICENSE=ABC1D2E345PROD=1234567OPTIONS1234567=1userPRICES1234567[USD]=50QTY=4PERIOD=30
The resulting upgrade link (excluding PHASH) is:
Secure upgrade links
Use an HMAC_SHA signature to prevent links from being exploited. To calculate the HMAC_SHA 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).
Using the parameters above, you get the following sequence:
You need to add the length of the character sequence at its beginning to calculate the hash, namely 90. The resulting base string is
For the purpose of this demo, let's assume that your secret key is SECRET_KEY.
Use the secret key and the base string to calculate the HMAC-SHA HASH. The result should be: sha256.6fd8d81dc6025a327edadb2a336e54554ef17a4152f2755f5011978403a61568 and sha3-256.4f79fc02ffc5d7612812fcccf9ca5ae5ba297ca7de1f223bffb3e74f76f9b80f (valid exclusively for this example).
The final upgrade link:
Domain use
secure.2checkout.com. If your account is using the 2Checkout's secure.2checkout.com domain, then your custom on-demand renewal links would look like this: https://secure.2checkout.com/order/upgrade.php?
Custom domains such as store.YourDomain.com. If your account is using a custom domain such as store.YourDomain.com, then your custom on-demand renewal links would look like this: https://store.YourDomain.com /order/upgrade.php?
Last updated
Was this helpful?