Skip to main content

Subscription renewal links

Last updated: 01-Mar-2024
Rate this article:

Overview

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

Availability 

All 2Checkout accounts. 

Requirements

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

Requirements 

Custom on-remand 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 deadline. Contact 2Checkout directly if you wish to customize this limitation.

Scenarios covered 

  1. Renew Subscription A belonging to Product A (source product) keeping it under Product A (target product).
  2. 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 also create more complex early renewal links, controlling price, renewal and expiration deadlines as well as subscription lifecycles. 

Create a custom renewal link

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

  1. The main renewal link: https://secure.2Checkout.com/renewal/?
  2. 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, please make sure that the position of the parameters is the same when creating the link as well as when generating the HASH. For convenience, consider using them in this order: LICENSE, PRODS, OPTIONS, PRICES[Currency], PERIOD, and PHASH.

Parameter Required Description

LICENSE

Required

Unique 2Checkout subscription reference. This identifier is used to trigger the renewal process for a specific subscription.

PRODS

Required

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.

The product ID can be:

 

1. Identifier of the product (the source and the target product are the same) to which the subscription is already associated with. For example, Subscription A belonging to Product A can be renewed while preserving the connection to Product A. Following the on-demand renewal, Subscription A will continue to renew per the Product A's renewal settings and pricing configuration options.

 

2. Identifier of a different product (the target product) than the one associated with the subscription (the source product). For example,Subscription A belonging to Product A can be renewed while the customer is upgraded to Product B. Following the on-demand renewal,Subscription A will continue to renew per the Product B's renewal settings and pricing configuration options.

 

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. Note: Product IDs are different than Product Codes, also available in this area, but which you control.

 

Effect: permanent. 2Checkout associates the subscription with the target product following the custom on-demand renewal.

Note: PRODS override settings related to renewal with a different product.

OPTIONS

Optional

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. 

 

For scale pricing options, the parameters need to be built using the options code and the specific scale value. For example, for a Users scale from 1 to 10 and 11 to 50 with the code users, the parameter is OPTIONS=users=35 if you want customers to the pay the costs for 35 users.

 

The 2Checkout system uses the options to calculate the renewal costs that customers pay, unless you specify them using the PRICES parameter.

 

If missing, the 2Checkout system uses the default pricing options of the product with which the subscription is associated.

 

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.

 

Effect: 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.

PRICES[Currency]

Optional

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]&PRICES[Currency2]=[ FLOAT]&PRICES[Currency3]=[ FLOAT]

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.

 

If missing, 2Checkout calculates the price based on the default product settings and pricing options.

 

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:

PRICES[USD]=99.99&PRICES[EUR]=88.99&PRICES[GBP]=80.99. This example can be expanded to cover all transactional currencies active for your account.

 

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.

 

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.

 

Effect: 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.

 

Note: When sent, the PRICES value, overrides all product-side pricing settings, including custom renewal prices and the usage of original order prices for renewals.

 

Note: 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.

QTY Optional

The product quantity of the renewal order. Example: QTY=5.

The value set overrides the quantity from the order that generates the renewal. The quantity value only impacts the price per unit, but has no impact on the final renewal price.

Include this parameter in the PHASH signature.

PERIOD

Optional

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.

 

If missing, the subscription renewal takes into account the entire billing cycle interval of the product with which the subscription is associated.

 

Effect: 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.

LANG Optional

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.

 

Check here the list of languages available.

IGNORE_CUSTOM_PRICE Optional

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.

 

Possible values: 1.

PHASH

Required

Required HMAC_MD5 signature in order to prevent the request from being exploited. Read the examples below to understand how to build the PHASH.

Effect: one-time only. Valid only for the link it's generated for.

Note: If you include the IGNORE_CUSTOM_PRICE parameter in the link, you need to generate a new PHASH.

Use cases

Renew the subscription with a specific price, quantity and period of 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 with 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

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:

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: 

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

3. For the purpose of 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-MD5 HASH. The result should be: 3f3b3dc0a9ceda2fb1daad4d5eec0b04 (valid exclusively for this example).

5. Build your complete link:

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

Renew a subscription with a specific price, quantity and period of 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
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: 

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:

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-MD5 HASH. The result should be: 0e06b3dfce123db20dae02a3fccfd3dd (valid exclusively for this example).

5. Build your complete link:

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

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 some aspects of the ordering experience for customers using early renewal links, by appending the following parameters to the created buy-link. The parameters listed below are not included in the PHASH calculation and can be added to links without recalculating the mandatory HMAC_MD5 signature.

Parameter Required/Optional Description

DESIGN_TYPE

Optional

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. 

LAYOUT_TYPE

Optional

LAYOUT_TYPE enables you to control which version of the shopping cart is served to shoppers. Possible values:

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);

MOBILE - 2Checkout mobile cart (using LAYOUT_TYPE=MOBILE will always display the mobile version of the shopping cart, even to users of desktop browsers).

REF

Optional

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 md5 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.

SRC

Optional

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: 

SRC=prodpage for the product page or SRC=dldpage for the link on the download page 

(dldpage and prodpage are example strings only, you can use any combination).

COUPON

Optional

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). 

For example: [...]&COUPON=voucher1,voucher2[...]

CARD

Optional

Possible values:

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.

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.

ORDERSTYLE

Optional

Allows you to set the corresponding 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

Include AUTO_PREFILL=1 in buy links for shopping carts.

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.

Address, City, and State details are calculated automatically by the 2Checkout system. The address can miss altogether.

Note: 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. 

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 
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 
https://store.YourDomain.com/renewal/?

 

Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo