Subscription renewal links

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.

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.

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.

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.

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.