# Subscription renewal links

## Overview

You can build and control manual subscription renewal links to offer directly to your customers.

## Availability

All 2Checkout accounts.

## Requirements

Custom renewal links can be created for active and past-due subscriptions (excluding trials and non-recurring / lifetime subscriptions).

Custom on-demand renewals buy-links need to be generated manually, and they work for active and past-due subscriptions (excluding trials and non-recurring/lifetime subscriptions).

Subscriptions can be renewed on demand up to 4 years ahead of their expiration date. Contact [2Checkout](https://secure.avangate.com/cpanel/contact.php) directly if you wish to customize this limitation.

## Scenarios covered

* Renew **Subscription A** belonging to **Product A** (source product) keeping it under **Product A** (target product).
* Renew **Subscription A** belonging to **Product A** (source product) and moving/upgrading the customer to **Product B** (target product).

## Workflow

Use this feature to enable your customers to renew their active and past-due subscriptions on-demand, bypassing the upcoming renewal operation scheduled in the 2Checkout system.

Custom on-demand subscription renewals are performed:

1. Using the price you specify, or by calculating the renewal costs based on the pricing options of the target product, or the custom renewal price for upcoming billing cycles, if set. The costs of all future renewals will be calculated based on the pricing options of the product with which the subscription is associated.
2. From the moment when the items were scheduled to renew/expire. For example, let's assume that **Subscription A** (a monthly subscription), scheduled to expire June 30th, 2013, is renewed through the use of an on-demand link with a period of 10 days on June 22nd. **Subscription A's** lifetime will be prolonged with 10 days starting with June 30th, and the renewal/expiration deadline moved to July 10th. Moving forward, **Subscription A** will be renewed a month after the July 10threnewal, per its monthly renewal cycle.
3. By overriding the subscription billing cycle settings. However, following the custom on-demand renewal, the subscription will be governed by the renewal settings and pricing configuration of the product it's associated with.

## Early renewals

In addition to standard manual renewal links, you can create early renewal links that control price, renewal and expiration deadlines, and subscription lifecycles.

## Create a custom renewal link

To build custom renewal links you need the following two elements:

* The main renewal link: [https://secure.avangate.com/renewal/?](https://secure.2Checkout.com/renewal/?)
* The unique subscription reference from the 2Checkout system: **LICENSE=1A22223BC4**

```
The simplest renewal link you can build is https://secure.2checkout.com/renewal/?LICENSE=1A22223BC4.
```

Tailor your renewal offer by controlling the renewal quantity and price.

## Parameters

When building custom on-demand renewal links, make sure the position of the parameters is the same when creating the link and when generating the PHASH. For convenience, consider using this order: LICENSE, PRODS, OPTIONS, PRICES\[Currency], PERIOD, and PHASH.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="192.0001220703125">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>LICENSE</code></td><td><p><strong>Required</strong></p><p>Unique 2Checkout subscription reference. This identifier is used to trigger the renewal process for a specific subscription.</p></td></tr><tr><td><code>PRODS</code></td><td><p><strong>Required</strong></p><p>The unique numeric (int) product ID from the 2Checkout system. Custom on-demand subscription renewals work for a single product at a time. As such, custom renewal links can contain only a single product identifier.</p><p></p><p>The product ID can be:</p><ol><li>Identifier of the product (the source and the target product are the same) to which the subscription is already associated with. For example, <strong>Subscription A</strong> belonging to <strong>Product A</strong> can be renewed while preserving the connection to <strong>Product A</strong>. Following the on-demand renewal, <strong>Subscription A</strong> will continue to renew per the <strong>Product A's</strong> renewal settings and pricing configuration options.</li><li>Identifier of a different product (the target product) than the one associated with the subscription (the source product). For example,<strong>Subscription A</strong> belonging to <strong>Product A</strong> can be renewed while the customer is upgraded to <strong>Product B</strong>. Following the on-demand renewal,<strong>Subscription A</strong> will continue to renew per the <strong>Product B's</strong> renewal settings and pricing configuration options.</li></ol><p>In the Control Panel, click to edit a product, and select the Information tab. The Product ID of the item you're editing is available at the top of the General area under Information. <em><strong>Note:</strong></em> Product IDs are different than Product Codes, also available in this area, but which you control.</p><p></p><p><strong>Effect:</strong> permanent. 2Checkout associates the subscription with the target product following the custom on-demand renewal.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>PRODS override settings related to renewal with a different product.</p></div></td></tr><tr><td><code>OPTIONS</code></td><td><p><strong>Optional</strong></p><p>Preselected pricing options for the target renewal product. The values used are the pricing options codes (the codes are set for each option individually). When a list of pricing options codes is used the values should be separated by commas. For example: OPTIONS=5usr,2year. Pricing options codes are case sensitive. </p><p> </p><p>For scale pricing options, the parameters need to be built using the options code and the specific scale value. For example, for a <strong>Users</strong> scale from 1 to 10 and 11 to 50 with the code <strong>users</strong>, the parameter is <strong>OPTIONS=users=35</strong> if you want customers to the pay the costs for 35 users.</p><p> </p><p>The 2Checkout system uses the options to calculate the renewal costs that customers pay, unless you specify them using the PRICES parameter.</p><p> </p><p>If missing, the 2Checkout system uses the default pricing options of the product with which the subscription is associated.</p><p> </p><p>2Checkout uses required pricing options to calculate renewal costs whether they're included in the custom link or not. At the same time, options that are not associated with the product are ignored.</p><p> </p><p><strong>Effect:</strong> permanent. 2Checkout associates the pricing options with the subscription following the custom on-demand renewal and will be used by the system to calculate the costs that customers will pay for future renewals.</p></td></tr><tr><td><code>PRICES[Currency]</code></td><td><p><strong>Optional</strong></p><p>Use this parameter to set the custom price for the subscription renewal in the default currency, as well as in all the transactional currencies active for your account. Multiple PRICES[Currency] parameters can be set to control renewal costs in various currencies: PRICES[Currency1]=[FLOAT]&#x26;PRICES[Currency2]=[ FLOAT]&#x26;PRICES[Currency3]=[ FLOAT]</p><p>When sent, the price takes precedence and overrides the renewal costs calculated by the 2Checkout system based on the pricing options (OPTIONS) included in the custom on-demand link.</p><p> </p><p>If missing, 2Checkout calculates the price based on the default product settings and pricing options.</p><p> </p><p>For example, let's assume that only 3 transactional currencies are active for your account, USD, EUR and GBP. You can price the renewal of a subscription as such:</p><p>PRICES[USD]=99.99&#x26;PRICES[EUR]=88.99&#x26;PRICES[GBP]=80.99. This example can be expanded to cover all transactional currencies active for your account.</p><p> </p><p>Customers see the prices defined per the currency they use when accessing the shopping cart during the ordering process. Considering the example above, shoppers in the US will pay $99.99 for their subscription renewal, while those in the UK will pay 80.99 GBP, even if the same link is used for both.</p><p> </p><p>If the price is not defined for a specific billing currency, the renewal costs calculated will be converted from the pricing defined for the product's default currency.</p><p> </p><p><strong>Effect:</strong> one-time only. Following the custom on-demand renewal, the 2Checkout system calculates the costs paid by customers for future renewals, based on the pricing options saved for this subscription and the product it's associated with.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>When sent, the <code>PRICES</code> value, overrides all product-side pricing settings, including custom renewal prices and the usage of original order prices for renewals.</p><p>If missing for a subscription for which you defined a custom renewal price for one or more upcoming billing cycles, the costs paid by the users will reflect the custom renewal price and will not be calculated using product pricing options.</p></div></td></tr><tr><td><code>QTY</code></td><td><p><strong>Optional</strong></p><p>The product quantity of the renewal order. Example: QTY=5.</p><p>The value set overrides the quantity from the order that generates the renewal. The quantity value only impacts the price per unit, but <strong>has no impact on the final renewal price.</strong></p><p>Include this parameter in the <strong>PHASH signature</strong>.</p></td></tr><tr><td><code>PERIOD</code></td><td><p><strong>Optional</strong></p><p>The interval of time in days that will be added to the subscription lifetime starting with the current renewal/expiration deadline. Cannot be larger than three (3) years.</p><p> </p><p>If missing, the subscription renewal takes into account the entire billing cycle interval of the product with which the subscription is associated.</p><p> </p><p><strong>Effect:</strong> one-time only. Following the custom on-demand renewal, the subscription will be renewed based on the billing cycle settings of the product it's associated with.</p></td></tr><tr><td><code>LANG</code></td><td><p><strong>Optional</strong></p><p>Selected language for order processing interface and payment receipt and fulfillment emails. By default, if the parameter is missing, the ordering process language is the same as the one used to buy the subscription.</p></td></tr><tr><td><code>IGNORE_CUSTOM_PRICE</code></td><td><p><strong>Optional</strong></p><p>The parameter applies the initial base price of the subscription, ignoring any custom price that you may have set. If you include this parameter in the link, you need to generate the PHASH again.</p><p> </p><p>Possible values: 1.</p></td></tr><tr><td><code>PHASH</code></td><td><p><strong>Required</strong></p><p>Required HMAC_SHA signature in order to prevent the request from being exploited. Read the examples below to understand how to build the PHASH.</p><p></p><p><strong>Effect:</strong> one-time only. Valid only for the link it's generated for.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If you include the IGNORE_CUSTOM_PRICE parameter in the link, you need to generate a new PHASH</p></div></td></tr></tbody></table>

## Use cases

### Renew the subscription with a specific price, quantity, and time

For this example, let's assume that we need a custom on-demand renewal link for **Subscription A** (monthly subscription expiring on June 30th, 2013, 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 a quantity of 5. We'll use some of the parameters listed above:

**LICENSE=ABC1D2E345**\
**PRODS=1234567**\
**OPTIONS=1user**\
**PRICES\[USD]=50**\
**QTY=5**\
**PERIOD=30**

```apache
https://secure.2checkout.com/renewal/?LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&QTY=5&PERIOD=30
```

You will need to build the **PHASH** for the link above.

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

   ```
   LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&QTY=5&PERIOD=30
   ```
2. Next, you need to prefix (prepend) the length of the character sequence to calculate the hash, namely 77. The resulting **BASE STRING** is: <br>

   ```
   77LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&QTY=5&PERIOD=30
   ```
3. For this example, 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.4f7bcf47639f518459fba6240616d21af1b70de2f378f26c22d76237e2d0e591** and **sha3-256.2051122ec103f9a2496bae2547e44daea91be9c8d2b0d395f3395857c651f385** (valid exclusively for this example).
5. Build your complete link:<br>

   ```
   https://secure.2checkout.com/renewal/?LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&QTY=5PERIOD=30&PHASH=sha256.4f7bcf47639f518459fba6240616d21af1b70de2f378f26c22d76237e2d0e591

   https://secure.2checkout.com/renewal/?LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&QTY=5PERIOD=30&PHASH=sha3-256.2051122ec103f9a2496bae2547e44daea91be9c8d2b0d395f3395857c651f385
   ```

### Renew a subscription with a specific price, quantity, and time, changing the product associated with the subscription

For this example, let's assume that we need a custom on-demand renewal link for **Subscription A** (monthly subscription expiring on June 30th, 2013 with the reference **ABC1D2E345**) associated with **Product A** with the **ID 1234567**. In the renewal process, the customer will also be upgraded from **Product A** to **Product B** (**ID 1122334**).

**Product A** is offered to customers in two versions:

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

**Product B** is offered to customers in a single version:

* 1 user (code: 1userPB - default, required option) - $199.99;

You're looking to prolong the subscription lifetime by 60 days, and charge the customer $160. We'll use some of the parameters listed above:

**LICENSE=ABC1D2E345**\
**PRODS=1122334**\
**OPTIONS=1userPB**\
**PRICES\[USD]=160**\
**QTY=5**\
**PERIOD=60**

```html
https://secure.2checkout.com/renewal/?LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&QTY=5&PERIOD=60
```

You need to build the **PHASH** for the link above.

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

   ```
   LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&QTY=5&PERIOD=60
   ```
2. Next, you need to prefix (prepend) the length of the character sequence to calculate the hash, namely 80. The resulting **BASE STRING** is:<br>

   ```
   80LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&QTY=5&PERIOD=60
   ```
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.d070ee274a5ebb90ec2b887e39116789d2a18b6474be3dc5351a72b7d0373821** and **sha3-256.c092eff5105a0d990eab1e3e571e4fb01ced19eb9d98e3fdcab8d7ef24efc9c7** (valid exclusively for this example).
5. Build your complete link:<br>

   ```
   https://secure.2checkout.com/renewal/80LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&QTY=5&PERIOD=60&PHASH=sha256.d070ee274a5ebb90ec2b887e39116789d2a18b6474be3dc5351a72b7d0373821
   https://secure.2checkout.com/renewal/80LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&QTY=5&PERIOD=60&PHASH=sha3-256.c092eff5105a0d990eab1e3e571e4fb01ced19eb9d98e3fdcab8d7ef24efc9c7
   ```

## Convert a trial on-demand

2Checkout converts all trials with payment information automatically, unless customers opt out. You can use the 2Checkout API to convert trials on demand.

## Control the ordering experience for early renewals

You can control aspects of the ordering experience for customers using early renewal links by appending parameters to the buy-link. These parameters are not included in the PHASH calculation and can be added without recalculating the HMAC\_SHA signature.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="152.99993896484375">Parameter</th><th>Type / Description</th></tr></thead><tbody><tr><td><code>DESIGN_TYPE</code></td><td><p><strong>Optional</strong></p><p>Value = 1. When DESIGN_TYPE=1 is used in Buy Links the parameter changes the layout of the shopping cart template interface, positioning the payment methods selector in a more prominent position, above the billing details area.</p></td></tr><tr><td><code>LAYOUT_TYPE</code></td><td><p><strong>Optional</strong></p><p>LAYOUT_TYPE enables you to control which version of the shopping cart is served to shoppers. Possible values:</p><p>CLASSIC - the desktop variant of the shopping cart (using LAYOUT_TYPE=CLASSIC will always display the desktop version of the cart even to mobile device users);</p><p>MOBILE - 2Checkout mobile cart (using LAYOUT_TYPE=MOBILE will always display the mobile version of the shopping cart, even to users of desktop browsers).</p></td></tr><tr><td><code>REF</code></td><td><p><strong>Optional</strong></p><p>External order reference (string). You can add a string identifier to every Buy Link created (less than 100 characters), and that will be saved with the order, in addition to the system-generated 2Checkout order reference. If there is a need for longer references, an sha2/3 hash can be applied for any string value, resulting in a 32 characters string. This hash can be verified after the order notification, on the client-side. External references are visible when accessing the order details page for your orders.</p></td></tr><tr><td><code>SRC</code></td><td><p><strong>Optional</strong></p><p>To identify the source of your sales (which links are performing better), a separate link identifier can be assigned to each link. For instance, if there are two buy links on your website, one in the product page and another one on the download page, you can track the source page by entering the following parameters:
<br>SRC=prodpage for the product page or SRC=dldpage for the link on the download page
<br>(dldpage and prodpage are example strings only, you can use any combination).</p></td></tr><tr><td><code>COUPON</code></td><td><p><strong>Optional</strong></p><p>Promotion coupon code to be applied in the order. You can send multiple values separated by a comma (in case you need several coupons to be applied in the same order). <br><em>For example: [...]&#x26;COUPON=voucher1,voucher2[...]</em></p></td></tr><tr><td><code>CARD</code></td><td><p><strong>Optional</strong></p><p>Possible values:</p><p>1 - use this parameter with value 1 in order to display the credit card details form on the selected landing page. Shoppers will place orders from the Review page.</p><p>2 - when this value is used, it not only allows the credit card details form to be displayed on the selected landing page but also enables shoppers to place orders immediately after entering their payment data, excluding the Review page.</p></td></tr><tr><td><code>ORDERSTYLE</code></td><td><p><strong>Optional</strong></p><p>Allows you to set the corresponding template, overriding the default template assigned to the product group. Each template defined in the <a href="https://secure.avangate.com/cpanel/design.php">Interface Templates area</a> of the Control Panel has a unique identifier associated which is visible in the browser address bar when previewing the shopping cart.</p></td></tr><tr><td><code>AUTO_PREFILL=1</code></td><td><p><strong>Optional</strong></p><p>Include <strong>AUTO_PREFILL=1</strong> in buy links for shopping carts.</p><p>When the AUTO PREFILL feature is active and AUTO_PREFILL=1 is used in buy links, the ZIP code and country pair become the only required aspects of the billing address.</p><p>Address, City, and State details are calculated automatically by the 2Checkout system. The address can miss altogether.</p><p><em><strong>Note:</strong></em> 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. </p></td></tr></tbody></table>

## Domain use

* **secure.2checkout.com** domain. If your account is using the 2Checkout's **secure.2checkout.com** domain, then this is what you need to include in your custom on-demand renewal links served to your customers, namely&#x20;

```html
https://secure.2checkout.com/renewal/?
```

* Custom domains such as **store.YourDomain.com**. If your account is using a custom domain such as **store.YourDomain.com**, then this is what you need to include in your custom on-demand renewal links served to your customers, namely&#x20;

```html
https://store.YourDomain.com/renewal/?
```


---

# 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/subscription-renewal-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.