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

dynamic Required for dynamic products Boolean. Set TRUE for dynamic products.
prod 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.

prod For dynamic products

Set the dynamic parameter TRUE to use dynamic products in the ordering process.

When using dynamic products, the prod parameter contains as value the name of the dynamic product. For multiple products, send them separated by a semicolon.

Example: name1;name2;name3.

item-ext-ref For dynamic products Set product identifier for your dynamic products. When included, the parameter needs to be signed.
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 a 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. The description field is displayed only for the 'One column with payment buttons' template. The description will not be visible in the default template.
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.

subscription

Required for the manual renewal of catalog products 

Unique system-generated identifier of your subscriptions. The subscription reference is available on Orders and customers à Subscriptions à Edit subscription details.

expiration Optional Buy link expiry date. The link becomes invalid after the date from this parameter. Send as a UTC timestamp. Example: 

1537549421 

return-url Optional URL to which customers are redirected after their finalized purchase. Learn more about Redirect URL on this article.
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-ext-ref 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.
  • Was this article helpful?