Skip to main content
knowledgecenter.2checkout.com

ConvertPlus URL parameters

Overview

Use 2Checkout ConvertPlus to provide your customers with a swift and safe payment experience. Depending on your desired workflow, you can either create ordering interface links using our dedicated interface (ConvertPlus) or generate the parameters dynamically, in your own system.

2Checkout enables you to use ConvertPlus with both catalog products, and with products generated dynamically via buy link parameters.

Availability 

Eligible 2Checkout accounts. Contact 2Checkout to inquire about ConvertPlus. 

Requirements 

To use ConvertPlus dynamic ordering, pass the dynamic parameter with TRUE or 1 value. When creating orders with catalog products, the prod parameter should contain the product code of your catalog item. For dynamic ordering, the prod parameter should contain the name of your dynamic product.  

How to create dynamic ConvertPlus buy links

  1. Start from the base ConvertPlus buy link:

     https://secure.2checkout.com/checkout/buy/?
    
  2. Add your merchant code to the buy link, so that 2Checkout links the sale to your account. Your merchant code can be found in your Control Panel, in the Account Information area. Example: merchant=2COLRNC.

  3. Set the dynamic parameter to TRUE or 1.

  4. Add product information such as product typename, price and quantity.

  5. Include additional product information, such as recurring options or customer redirect URL.

Sample ConvertPlus buy link for dynamic product information

The following buy link reproduces a dynamic ordering experience:

https://secure.2checkout.com/checkout/buy/?merchant=2COLRNC&dynamic=1&name=2CheckoutSubscription&type=PRODUCT&qty=1&price=10&test=1

Buy link parameters

 When you generate a checkout link, 2Checkout automatically includes some of the parameters in the list below in the URL, depending on a number of variables, such as the products, discounts, currency, and more. You can use these query parameters to generate checkout links in your own system, without having to rely on the functionality in you account. 

Parameter Required/Optional Description

Billing information

 

Use these parameters to control the billing information displayed in the shopping cart. By adding this parameters in the buy link, you can pre-fill the customer information and minimize the customer effort in the ordering process.

email Optional Send customer email.
name Optional Send full customer name. Ex: "John Steward Doe".
phone Optional Send customer phone number.
country Optional Send customer country code. Two-digits code. Ex: "UK".
state Optional Send customer state code. Two-digits code. Ex: "CA".
address Optional Send customer address.
address2 Optional Send customer additional address information.
zip Optional Send customer zip code.

Delivery information

 

Use these parameters to control the billing information displayed in the shopping cart. By adding this parameters in the buy link, you can pre-fill the customer information and minimize the customer effort in the ordering process.

ship-name Optional Send customer delivery name. Ex: "John Steward Doe".
ship-country Optional Send customer delivery country code. Two-digits code. Ex: "UK".
ship-state Optional Send customer delivery state code. Two-digits code. Ex: "CA".
ship-address Optional Send customer delivery address.
ship-address2 Optional Send customer additional delivery address information.
ship-zip Optional Send customer delivery zip code.

Product information

 

Use the parameters to create products with dynamic information, skipping the need of handling a product catalog in your 2Checkout Control Panel.

prod Required for catalog products Product codes added to checkout, separated by a semicolon.

Do not use spaces or blanks. Example: prod=46CC15F39;7488E17CC0. Product codes are assigned by you at the moment you are adding new products.

In the Control Panel, click to edit a product, and select the Information tab. The Product code of the item you're editing is available at the top of the General area under Information.

Warning: Changing a product code already used in active buy links will completely break the checkout flow for those links. If you change a product code, make sure all your buy links for that product are replaced with new links generated with your current product code.

name Required for dynamic products

Name of the dynamic product. For multiple products, send them separated by a semicolon.

Example: name1;name2;name3.

type Required for dynamic products

The type of the dynamic product. Possible values:

  • PRODUCT
  • SHIPPING
  • TAX

For multiple dynamic  items, send the values separated by a semicolon.

qty Required 

The number of units (quantity) for each product in checkout, separated by semicolon ;. Do not use spaces or blanks. Example: qty=2;1.

qty works in conjunction with prod, based on their respective order. The first value of the qty parameter controls the number of units for the products whose identifier is in the first position of the prod parameter. 

Example: https://secure.2checkout.com/checkou...rchant=2COLNC&prod=6FD08E61B5;E2932D0DE2&qty=4;3

price Required for dynamic products

For dynamic products, enter the product price.

For multiple dynamic items, send the values separated by a semicolon.

Example: price1;price2;price3.

tangible Required for dynamic products

Boolean.

Send TRUE or 1 for products that require physical delivery.

opt Optional Defines the product pricing options.

 

URL formating rules:

 

":" is considered a pair separator

  • 1 product with 1 price option with 1 value (includes scale option type)
    • prod=code1&opt=gr1:val1
  • 1 product with 1 price option with multiple values
    • prod=code1&opt=gr1:val1:val2

 

"," is considered a value separator

  • 1 product with 2 price options with 1 value each
    • prod=code1&opt=gr1:val1,gr2:val2
  • 1 product with 2 price options with multiple values each
    • prod=code1&opt=gr1:val1:val2,gr2:val3:val4

 

";" is considered a parameter separator between products

  • 2 products with 1 price option containing 1 value
    • prod=code1;code2&opt=gr1:val1;gr2:val2
  • 2 products with 1 price option containing multiple values
    • prod=code1;code2&opt=gr1:val1:val2;gr2:val3:val4
  • 2 products with 2 price options containing 1 value each
    • prod=code1;code2&opt=gr1:val1,gr2:val2;gr3:val3,gr4:val4
  • 2 products with 2 price options containing multiple values each
    • prod=code1;code2&opt=gr1:val1:val2,gr2:val3:val4;gr3:val5:val6,gr4:val7:val8
description Optional for dynamic products For dynamic products, set a description that is displayed in the checkout page.
recurrence Optional for dynamic products

For dynamic products, set product recurring options.

Send multiple dynamic items separated by a semicolon.

Example: period1:unit1;period2:unit2;

 

Possible values for units:

  • DAY
  • WEEK
  • MONTH
  • YEAR
  • FOREVER
duration Optional for dynamic products For dynamic products, set the duration of the recurrence.
renewal-price Optional for dynamic products For dynamic products, set the price that should be applied on the renewal order.

Cart behavior

 

Use the parameters below to control the purchasing flow. You can add a success URL for your finalized orders, change the cart template, add a source parameter or choose to place test orders.

merchant Required Your merchant identification code. The merchant code is available in Settings > Edit system settings, under the System settings tab.
dynamic Required for dynamic products Boolean. Set TRUE for dynamic products.
return-url Optional URL to which customers are redirected after their finalized purchase. Learn more about Redirect URL on this article.

success-url

Optional

2Checkout redirects your shoppers to a custom URL after they successfully place an order. When using success-url you bypass 2Checkout’s hosted ‘Thank You’ page for instant payment methods (this impacts any tracking set up in the page) but not for offline payment methods such as bank/wire transfer.

return-type Optional

The return method used for redirecting your customers after a successful sale. Possible values:

  • Link in the Thank You page
  • Header Redirect

Read more about redirect URL.

coupon

Optional

Promotion coupon code discounting the price of a product added to checkout. You can send multiple values separated by semicolon when standalone coupons discount different products added to checkout. 
For example: [...]&coupon=voucher1;voucher2[...]

src Optional

Use this parameter to identify the source of your sales (which links are performing better).  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.

tpl Optional

Cart template used for the checkout experience.

Possible values:

  • default
  • one-column

Use the style parameter to send ConvertPlus cart themes customized via Cart Editor.

currency Optional Preselected billing currency 2Checkout uses to charge your customers.
empty-cart Optional Boolean. Use for resetting cart contents.
order-external-reference Optional Use this parameter to set an external reference to the order.
language Optional

Defines the language for the order interface. English is the default language.

Available values for language codes are displayed in this article.

origin-url Optional Set an origin URL for the purchase.
style Optional

Use style for setting a customized cart template for the checkout experience.

The parameter can be populated with the styling code assigned to each of your customized ConvertPlus cart themes. Contact 2Checkout to learn how to retrieve the styling code for your customized themes.

test Optional Use test=1 to place test orders. Exclude for regular order. Dummy credit card details are provided so you can test the entire order placing process. Guidance on the 2Checkout test ordering system is available here.