Skip to main content
knowledgecenter.avangate.com

Early renewals

Overview

Enable your customers to order on-demand renewals for their subscriptions using custom Buy Links.

Availability

All Avangate accounts. 

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 Avangate 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 Avangate 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 22ndSubscription 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.

Create the custom renewal link

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 Avangate 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 Avangate 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. Avangate 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 Avangate system uses the options to calculate the renewal costs that customers pay, unless you specify them using the PRICES parameter.

 

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

 

Avangate 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. Avangate 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 Avangate system based on the pricing options (OPTIONS) included in the custom on-demand link.

 

If missing, Avangate 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 Avangate 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.

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.

 

ar العربية Arabic

bg български език Bulgarian

cs Česky Czech

da Dansk Danish

de Deutsch German

el Ελληνικά Greek

en English

es Español Spanish

fa فارسی Persian

fi Suomi Finnish

fr Français French

he Hebrew עִבְרִית

hi Hindi

hr Hrvatski jezik Croatian

hu Magyar Hungarian

it Italiano Italian

ja 日本語 Japanese

ko 한국어 Korean

nl Nederlands Dutch

no Norsk Norwegian

pl Polski Polish

pt Português Portuguese

pt-br Português do Brasil Brazilian Portuguese

ro Română Romanian

ru Русский Russian

sk Slovenčina Slovak

sl Slovène Slovenian

sr Serbian

sv Svenska Swedish

th ไทย Thai

tr Türkçe Turkish

zh 中文 Chinese Simplified(Cantonese)

zy 繁体中文 Chinese Mandarin Traditional

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.

Scenarios

Renew the subscription with a specific price 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. We'll use the some of the parameters listed above:

LICENSE=ABC1D2E345

PRODS=1234567

OPTIONS=1user

PRICES[USD]=50

PERIOD=30

https://secure.avangate.com/renewal/?LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&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&PERIOD=30
  2. Next, you need to prefix (prepend) the length of the character sequence to calculate the hash, namely 71. The resulting BASE STRING is 71LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&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-MD5 HASH. The result should be: 5252071273bcbc52575e9b9551b82b3b (valid exclusively for this example).
  5. Build your complete link:
https://secure.avangate.com/renewal/?LICENSE=ABC1D2E345&PRODS=1234567&OPTIONS=1user&PRICES[USD]=50&PERIOD=30&PHASH=5252071273bcbc52575e9b9551b82b3b

Renew a subscription with a specific price 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 versions:

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

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

  • LICENSE=ABC1D2E345
  • PRODS=1122334
  • OPTIONS=1userPB
  • PRICES[USD]=160
  • PERIOD=60
https://secure.avangate.com/renewal/?LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&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&PERIOD=60
  2. Next, you need to prefix (prepend) the length of the character sequence to calculate the hash, namely 74. The resulting BASE STRING is 74LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&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: b172a31f2704f57417887845e4d0a0e1 (valid exclusively for this example).
  5. Build your complete link:
https://secure.avangate.com/renewal/?LICENSE=ABC1D2E345&PRODS=1122334&OPTIONS=1userPB&PRICES[USD]=160&PERIOD=60&PHASH=b172a31f2704f57417887845e4d0a0e1

Domain use

  1. secure.avangate.com domain - If your account is using the Avangate's secure.avangate.com domain, then this is what you need to include in your custom on-demand renewal links served to your customers, namely https://secure.avangate.com/renewal/?.
  2. 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/?

Convert a trial on-demand

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

Control the ordering experience 

You can control some aspects of the ordering experience for customers using early renewal links, by appending the following parameters to the buy link created. The parameters listed below are not included in 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 - Avangate 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 Avangate order reference. If there is a need for longer references, a md5 hash can be applied for any string value, resulting a 32 characters string. This hash that 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 in 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 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 in 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 in 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 theInterface 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 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 Avangate 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.