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 upgrade 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
https://secure.2checkout.com/order/upgrade.php?The unique subscription identifier from the 2Checkout system: LICENSE=ABC1D2E345. The simplest upgrade link you can build is:
https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345
Query parameters
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.
|
| 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, 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. |
| LICENSE | Required |
Specifies the subscription to be upgraded.
|
| 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). You need to append the unique product identifier generated by the 2Checkout platform after the OPTIONS parameter.
|
| 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 in a more prominent position, above the billing details area. |
| LAYOUT_TYPE | Optional |
Enables you to control which version of the shopping cart 2Checkout serves to shoppers. Possible values:
|
| REF | Optional | External order reference (string). Add a string identifier to every URL (less than 100 characters). 2Checkout saves the string at order-level, in addition to the system-generated order reference. If there is a need for longer references, use an md5 hash. To access external reference info navigate to the order details page. |
| SRC | Optional | Identifies the source of a sale by assigning a unique URL identifier. For instance, if there are two buy links on your website, one in the product page and another one in the download page, you can track the source page by entering the following parameters:
|
| COUPON | Optional |
Promotion coupon code applied to the order. Use commas (,) to separate multiple values.
|
| CARD | Optional |
Possible values:
|
| ORDERSTYLE | Optional | Allows you to set the desired ordering interface template, overriding the default template assigned to the product group. Each template defined in the Interface Templates area of the Control Panel has a unique identifier associated which is visible in the browser address bar when previewing the shopping cart. |
| AUTO_PREFILL=1 | Optional |
Requires 2Checkout activation before using.
Use AUTO_PREFILL=1 to set the ZIP code and country fields as mandatory. Address, City and State details are calculated automatically by the 2Checkout system. The address can be excluded completely. Using the AUTO_PREFILL=1 parameter without the feature being enabled for your account will result in shoppers following 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 with 30 days, and charge the customer $50. For this example, the parameters must have the following values:
- LICENSE=ABC1D2E345
- PROD=1234567
- OPTIONS1234567=1user
- PRICES1234567[USD]=50
- QTY=4
- PERIOD=30
The resulting upgrade link (excluding PHASH) is:
https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[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).
- Using the parameters above, you get the following sequence:
LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30 - You need to add the length of the character sequence at its beginning, to calculate the hash, namely 90. The resulting base string is
90LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30 - 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-MD5 HASH. The result should be: 54e7d22d741f3ceacfe80586ba5d55a7 (valid exclusively for this example).
- The final upgrade link:
https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30&PHASH=54e7d22d741f3ceacfe80586ba5d55a7Domain 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?
