# 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** 

```apache
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:

```apache
https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345
```

## Query parameters

Build your upgrade links using the following parameters.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="262">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>LICENSE</code></td><td><p><strong>Required</strong></p><p>Specifies the subscription to be upgraded. </p><p><strong>Example</strong>: <code>https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345</code></p></td></tr><tr><td><code>PROD</code></td><td><p><strong>Required</strong></p><p>Product ID of the target product used in the upgrade process.</p></td></tr><tr><td><code>PRICES(ProductId)[CURRENCY]</code></td><td><p><strong>Required</strong></p><p>Price and currency to be used in the custom upgrade process. </p><p><strong>Example</strong>: <code>PRICES4692644[USD]=999</code></p></td></tr><tr><td><code>QTY</code></td><td><p><strong>Optional</strong></p><p>Set product quantity. It does not impact the total order price.</p></td></tr><tr><td><code>PERIOD</code></td><td><p><strong>Optional</strong></p><p>Period of time to replace the subscription lifetime. Starts when the order is finalized. Requires <code>PRICES</code> parameter.</p></td></tr><tr><td><code>PHASH</code></td><td><p><strong>Required</strong> if using <code>PRICE</code>, <code>PERIOD</code></p><p>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.</p></td></tr><tr><td><code>LANG</code></td><td><p><strong>Optional</strong></p><p>ISO country code of the language used for the order processing interface and shopper emails. Default value: EN.</p></td></tr><tr><td><code>CURRENCY</code></td><td><p><strong>Optional</strong></p><p>Preselects the billing currency to be used in the transaction.</p></td></tr><tr><td><code>SHOPURL</code></td><td><p><strong>Optional</strong></p><p>Custom URL used for "Back to shopping" link.</p></td></tr><tr><td><code>OPTIONS(ProductID)</code></td><td><p><strong>Optional</strong></p><p>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 <code>OPTIONS</code> parameter. </p><p><strong>Example</strong>: <code>OPTIONS1234567=5usr,2year</code></p></td></tr><tr><td><code>UPGRADEPROD</code></td><td><p><strong>Required</strong> in conjunction with <code>UPGRADEOPT</code>. <strong>Optional</strong> otherwise. </p><p>Product ID of the target product used in the upgrade process.</p></td></tr><tr><td><code>UPGRADEOPT</code></td><td><p><strong>Optional</strong></p><p>Product option code of the target product used in the upgrade process. Can only be used in conjunction with <code>UPGRADEPROD</code>.</p></td></tr><tr><td><code>DESIGN_TYPE</code></td><td><p><strong>Optional</strong></p><p>Use <code>DESIGN_TYPE=1</code> to change the layout of the shopping cart template interface, positioning the payment methods selector above the billing details area.</p></td></tr><tr><td><code>LAYOUT_TYPE</code></td><td><p><strong>Optional</strong></p><p>Controls which version of the shopping cart 2Checkout serves. Possible values: <code>CLASSIC</code> (desktop variant) or <code>MOBILE</code> (mobile variant).</p></td></tr><tr><td><code>REF</code></td><td><p><strong>Optional</strong></p><p>External order reference (string, &#x3C;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.</p></td></tr><tr><td><code>SRC</code></td><td><p><strong>Optional</strong></p><p>Identifies the source of a sale by assigning a unique URL identifier (e.g., <code>SRC=prodpage</code>).</p></td></tr><tr><td><code>COUPON</code></td><td><p><strong>Optional</strong></p><p>Promotion coupon code(s) applied to the order. Use commas to separate multiple values. Example: <code>&#x26;COUPON=voucher1,voucher2</code></p></td></tr><tr><td><code>CARD</code></td><td><p><strong>Optional</strong></p><p>Possible values: <code>1</code> to display the payment form in the selected landing page (Review page); <code>2</code> to display the payment form and place orders immediately after entering payment data (no Review page).</p></td></tr><tr><td><code>ORDERSTYLE</code></td><td><p><strong>Optional</strong></p><p>Overrides default ordering interface template. Each template in the Interface Templates area has a unique identifier.</p></td></tr><tr><td><code>AUTO_PREFILL=1</code></td><td><p><strong>Optional</strong> (requires 2Checkout activation)</p><p>Use <code>AUTO_PREFILL=1</code> 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.</p></td></tr></tbody></table>

## 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`=**ABC1D2E345**
* `PROD`=**1234567**
* `OPTIONS1234567`=**1user**
* `PRICES1234567[USD]`=**50**
* `QTY`=**4**
* `PERIOD`=**30**

The resulting upgrade link (excluding PHASH) is:

```apache
https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30
```

## 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](https://secure.avangate.com/cpanel/account_settings.php)).&#x20;

1. Using the parameters above, you get the following sequence:<br>

   ```
   LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30
   ```
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<br>

   ```
   90LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30
   ```
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-SHA HASH. The result should be: **sha256.6fd8d81dc6025a327edadb2a336e54554ef17a4152f2755f5011978403a61568** and **sha3-256.4f79fc02ffc5d7612812fcccf9ca5ae5ba297ca7de1f223bffb3e74f76f9b80f** (valid exclusively for this example).
5. The final upgrade link:<br>

   ```
   https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30&PHASH=sha256.6fd8d81dc6025a327edadb2a336e54554ef17a4152f2755f5011978403a61568

   https://secure.2checkout.com/order/upgrade.php?LICENSE=ABC1D2E345&PROD=1234567&OPTIONS1234567=1user&PRICES1234567[USD]=50&QTY=4&PERIOD=30&PHASH=sha3-256.4f79fc02ffc5d7612812fcccf9ca5ae5ba297ca7de1f223bffb3e74f76f9b80f
   ```

## 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**](https://secure.avangate.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**](https://store.yourdomain.com/) **/order/upgrade.php?**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.2checkout.com/subscriptions/subscriptions/subscription-management/custom-links/custom-upgrade-links.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.