updates RSS feed

Targeted promotions

Overview

Use targeted promotions to trigger promotions for your shoppers based on the sale source they originate from, increasing your conversion rate and maximizing customer lifetime value while accounting for various criteria, such as website URL or domain localization.

Availability

This feature is available to all 2Checkout accounts and applies only to Regular promotions.

Source parameter requirements 

  • Use UTF-8 encoding.
  • Use URL encoding if populating the SRC parameter with a link.
  • Consider hashing long URL parameters instead of using them as they are.

Workflow

  1. Define a product promotion by following the steps described here.
  2. Set the promotion to trigger automatically when shoppers add the products to checkout using this option Auto apply discount(instant discount), if you want to offer discounts based on the values of the SRC parameter alone, without requiring customers to enter a coupon code. 
  3. Use the Sources text box to define one or multiple sale sources that should trigger your promotion. Enter one source per line.
    • The sources are the values of the SRC parameter you include in the buy link.
  4. Generate buy links using the corresponding SRC parameters for each of your localized promotions.
    • Example: If you defined a promotion to be triggered by a source called HomePage, your buy link should contain the &SRC=HomePage parameter.

Use cases

Target shoppers in specific countries

Let's say you own three localized domains for your online store, each with the same product portfolio.

You might want to offer higher discounts to Spanish and French shoppers who buy Product A than you do to visitors buying from your international website.

Here's how to use this feature to do exactly that.

  1. Let's start by adding a promotion for international shoppers. Add a product promotion for Product A offering a discount of 15% by following the steps described here.
  2. Next, add the same promotion for the same product, with a discount of 20%, only this time, enter Spanish in the Sources box. This applies the 20% discount only to shoppers buying from www.YourStore.es. Save the promotion.
  3. Add a third promotion for the same product, offering a 25% discount. This time, enter French in the Sources box. This applies the 25% discount only to shoppers buying from www.YourStore.fr. Save the promotion.
  4. Follow the steps described here to generate three different buy links, one for each of your domains.
    • One buy link using the Spanish value for the link source parameter. Add this link to your www.YourStore.es store.
    • https://www.YourStore.es/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=Spanish
    • One buy link using the French value for the link source parameter. Add this link to your www.YourStore.fr store.
      https://www.YourStore.fr/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=French
    • One buy link with no source parameter for everyone else. Add this link to your www.YourStore.com store.
      https://www.YourStore.com/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1

Promotions triggered by sale sources take priority over promotions without a sale source. This means that 2Checkout automatically applies the second promotion to all orders placed on www.YourStore.es and the third promotion to all orders placed on www.YourStore.fr.

Orders placed on any other domain get the first promotion applied.

Target shoppers by geolocation

Let's say you own an international online store, with a standalone product portfolio and you need to differentiate discounts based on shopper geography, offering higher promotions to those in North and South America, compared to those in EMEA and Asia and Australia, when they acquire the same product, InternationalSubscription. 

Here's how to use this feature to do exactly that.

  1. Let's start by adding a promotion for North and South American shoppers. Add a product promotion for InternationalSubscription offering a discount of 30% by following the steps described here. Enter Americas in the Sources box.
  2. Next, add the same promotion for the same product, with a discount of 25%, only this time, enter EMEA in the Sources box. This applies the 25% discount only to shoppers buying Europe, Middle East, and Africa. 
  3. Add a third promotion for the same product, offering a 10% discount. This time, enter AsiaAndAU in the Sources box. This applies the 10% discount only to shoppers buying from Asia and Australia.
  4. Follow the steps described here to generate three different buy links, one for each of your domains.
    • One buy link using the Americas value for the link source parameter. 
    • https://www.YourStore.es/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=Americas
    • One buy link using the EMEA value for the link source parameter. 
      https://www.YourStore.fr/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=EMEA
    • One buy link using the AsiaAndAU value for the link source parameter.
      https://www.YourStore.com/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=AsiaAndAU

  5. Next, you need need to build logic on your online store to differentiate these users based on their location (IP geolocation) or on their browser language and serve the appropriate checkout links and the associated discounts. For example, shoppers located in the US and Canada would see the link below and get a 30% discount. 

    https://www.YourStore.es/order/checkout.php?PRODS=1234567&QTY=1&CART=1&CARD=1&SRC=Americas

Reporting

Monitor campaign results in real-time using the Top Promotions report or the Sales Source Report to see which links are performing better and identify the top converting promotions. 

Limitations

This feature is now available for affiliate or reseller (partner) promotions. 

 

 

Lead Management

Overview

2Checkout's lead management is a smart and easy way to reduce customer churn and gain useful insights into what drives customers to cancel automatic renewals. Use the Lead object to configure lead management campaigns via JSON-RPC API 6.0 to reduce unfinished payments and cart abandonment.

You can use lead management to:

  • run a report on unfinished payments
  • send abandoned shopping cart follow-up emails
  • request invoices

 

Partner

Overview

Use the Partner object to search and retrieve partner information.

Structure

Partner Object
PartnerCode String
  Unique identifier that you need to specify when creating a partner in the Control Panel. You can find it under the General Information area when editing partner details.
CompanyName String
  The name of your partner company.
Email String
  The partner email address specified in the Contact Information area.
CommunicationLanguage String
 

ISO 639-1 two-letter language code set for the communication language under Contact information.

Case sensitive: 'en' instead of 'EN'.

 

Possible values:

  • en
  • fr
  • de
Currency String
  The ISO code of the currency set for the partner - ISO 4217. This currency governs transactions between you and the partner. You can configure it in the Commercial settings section, under Payment information.
CreditLimit double
  The credit limit set for the partner. Can be NULL when no credit is offered.
AvailableCreditLimit double
  The credit still available to the partner, after the value of orders already placed but not paid was deducted from the total credit limit configured. Can be NULL when no credit limit is defined.

 

Customer

Attributes

Parameters

Type/Description

CustomerDetails

Object

 

AvangateCustomerReference

Optional (Int)

 

 

System-generated Avangate customer reference.

 

null when you create a new customer. The Avangate system generates default customer numerical (integer) IDs (AV_CUSTOMERID) automatically for all orders containing products that feature subscriptions.

 

 

Aggregate subscriptions under the same Customer account by adding the AV_CUSTOMERID (case sensitive) parameter to Buy links.

 

ExternalCustomerReference

Optional (string)

 

 

Unique customer alphanumeric (string) identifiers you control. Aggregate subscriptions under the same Customer account by adding the CUSTOMERID (case sensitive) parameter to Buy links.

 

FirstName

Required (string)

 

 

Customer's first name. 

 

LastName

Required (string)

 

 

Customer's last name.

 

Company

Optional (string)

 

 

Company name.

 

FiscalCode

Optional (string)

 

 

Can be null for end users. For companies, it needs to be the VAT ID, which Avangate validates.

Avangate throws an error if the VAT ID is invalid/incorrect. When present, you also need to provide the company name.

 

Can be null for end users.

 

Address1

Required (string)

 

 

Customer's address.

 

Address2

Optional (string)

 

 

Customer's address.

 

City

Required (string)

 

 

Customer's city.

 

State

Optional (string)

 

 

Customer's state. For example, "Alabama","Alaska","Arizona".

 

Zip

Required (string)

 

 

Zip code.

 

CountryCode

Required (string)

 

 

Customer's country code (ISO 3166 two-letter code).

 

Phone

Optional (string)

 

 

Customer's phone number.

 

Fax

Optional (string)

 

 

Customer's fax number.

 

Email

Required (string)

 

 

Customer's email.

 

ExistingCards

Optional (Array of objects)

 

 

 

 

 

TransientToken

Optional (Object)

 

 

 

Populated only with when you retrieve customer information by SSOToken.

 

 

 

Token

Optional (string)

 

 

 

 

Token for the EXISTING_PAYMENT_DATA flow. Use it to charge customers using cards they used in the past for purchases from your Avangate account.

 

 

CardType

Optional (string)

 

 

 

visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb

 

 

LastDigits

Optional (string)

 

 

 

Last four digits of the credit card.

 

 

ExpirationMonth

Optional (string)

 

 

 

Card expiration month.

 

 

ExpirationYear

Optional (string)

 

 

 

Card expiration year.

 

 

NameOnCard

Optional (string)

 

 

 

Card holder name.

 

Enabled

Optional (boolean)

 

 

true or false, depending on whether the customer account is active or inactive. An active customer account features at least one Active or Past due subscription. Possible customer statuses:

 

  • Active - Customer account status is Active even if Trial and Cancelled/Expired subscriptions exist for the customer, along as there's at least one Active subscription. Customers with a single subscription featuring the Past due status (expired but in the grace period) are considered Active.
  • Inactive - All subscriptions associated to this Customer account are cancelled, expired or both.
  • Trial - Customer account status is Trial if all Active subscriptions for this customer are trials, regardless of any Cancelled/Expired subscriptions.

 

Trial

Optional (boolean)

 

 

true or false, depending on whether the customer account features only trials or also paid subscriptions.

 

Language

Optional (string)

 

 

ISO 639-1 two-letter code. Example: “en.”

 

Promotion

Overview

The object below is returned directly or within a successful response from the following API requests:

Create promotion                          Update promotion                            Retrieve a promotion                            Search promotions

Promotion object

Parameters Type/Description

CouponCodes

Array of strings

 

Array of coupon/voucher codes when Coupon / Voucher type is Multiple. Otherwise, empty array.

ChannelType

String

 

Possible values:

  • ECOMMERCE
  • CHANNEL_MANAGER
  • ALL

CouponType

String

 

Possible values:

  • SINGLE
  • MULTIPLE

DiscountType

String

 

Possible values:

  • FIXED
  • PERCENT

Type

String

 

REGULAR
PriceMatrixPriceMatrix Array of objects (only for SPECIAL_PRICE type of promotion)
  Is generated by the getPriceMatrix call and used to set promotion special prices.

ProductCode

 String
  Code of the product that is used by promotion.

PricingConfigurationCode

 String
  Code of pricing configuration used by promotion; must be related to the product.

OptionHash

 String
  Unique identifier of one combination of price configuration options.

Options

 Array of objects
  Describes price configuration options identified by OptionHash.

GroupName

 String

OptionText

 String

Prices

 Array of objects
  Promotion prices by currency; the price for default currency is required.

Value

 Int/Required
  Decimal

Currency

 String
  ISO code.

Discount

Int

 

The value of the discount. Example, for a $30 USD discount 2Checkout returns the value 30 and for a 25% price cut, 2Checkout returns 25.

Products

Array

 

Array of product codes for the products impacted by the promotion.

Name

String

 

Promotion name.

Description

String

 

Promotion description.

StartDate

String

 

Starting date. The date when you set the promotion to start. Is NULL for promotions that start immediately after they're created.

EndDate

String

 

Ending date. The date when you set the promotion to end. Is NULL for promotions that you want active indefinitely.

MaximumOrdersNumber

Int

 

When the maximum number of orders is reached the promotion stops. Can be NULL if you want the promotion to apply to an unlimited number of orders.

MaximumQuantity

Int

 

Discount only applies to a specific number of product, smaller than the maximum quantity you defined. Can be NULL if you want the promotion to apply to an unlimited number units. Any extra quantity added to the cart will be sold at full price.

InstantDiscount

Boolean

 

Selecting the instant discount option will auto-apply the discount for ALL the selected products for all shoppers, without the need to enter the discount coupon.

Coupon

String

 

The promotion/voucher for which you are extracting the information.

DiscountLabel

String

 

Discounts can be set as a percentage from the product price or as a fixed amount in the chosen currency.

Enabled

Boolean

 

 Can be TRUE if promotion is enabled, or FALSE if otherwise.

Currency

String

 

Currency code available for the default currency of FIXED promotions. Missing for PERCENT promotions.
DefaultCurrency String
  Required for SPECIAL_PRICE promotions, represents the default currency of the promotion.

Code

String

 

Unique, system-generated identifier 2Checkout associates with promotion campaigns.

PriceThreshold

Object

 

Limits discount use only when total order value (taxes included) exceeds the threshold you configure.

 

Amount

 Decimal

 

 

The minimum threshold you defined for the default currency.

 

Currency

String

 

 

Currency code available for the default currency of custom threshold settings.

Usage management

Overview

The usage-based/on-demand/pay-as-you-go pricing model allows merchants to charge their customers on the consumption or overage of a billable service or resource, usually on top of a recurring flat rate. 

Use the Usage object to manage (add, update, delete, retrieve, and import) usage via the 2Checkout API (SOAP API 6.0).

Parameters

Parameters for the Usage object via SOAP API 6.0
Parameters Type Required/Optional Description
UsageReference Integer Optional The unique usage identifier. Example: 123459876.
SubscriptionReference String Required Unique code that represents a subscription. Example: 83FE4FEF2.
OptionCode String Required Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing.
UsageStart Datetime Required The datetime when the usage started; can be the same as UsageEnd.  Example: 2018-09-03 17:28:32.
UsageEnd Datetime Required The datetime when the usage ended and was recorded. Example: 2018-09-03 17:28:32.
Units Integer Required Number of units recorded. Example: 10.
Description String Optional It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September.

 

 

Minimize required checkout data

Overview

Use this feature to streamline the shopping cart by minimizing data entry and providing an optimized ordering experience for customers.

Availability

Available by default to 2Monetize accounts.

Requirements

This feature requires the use of the SHORT_FORM parameter in buy-links generated in the Merchant Control Panel.

The SHORT_FORM parameter is case sensitive.

Purchase flow support

This feature supports the following purchase flows:

  • Checkout with cart functionalities
  • One page checkout with review
  • One page checkout without review
  • Add to shopping cart
  • Checkout page
  • Product page
  • Express Payments Checkout
  • Trial links

Generate buy-links with the SHORT_FORM parameter

  1. Log in to your 2Checkout Merchant Control Panel account.
  2. Navigate to the Generate Links area.
  3. Check the checkbox for the Compact shopping cart fields option when generating your buy-link to minimize the number of mandatory cart fields shoppers need to fill in during the purchase process. This action will automatically add the SHORT_FORM=1 parameter to the generated buy-links.

Create buy-links with the SHORT_FORM parameter manually

You can also add the SHORT_FORM=1 parameter manually to buy-links for shopping carts after you generate them.

When the feature is active for your account, and SHORT_FORM=1 is used in buy-links, the name, email, ZIP code, and country pair become the only required details of the billing address.

Using the SHORT_FORM=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.

Workflow

Customers accessing buy-links that include the SHORT_FORM parameter after the feature has been enabled for your account will need to:

  1. Fill in only the country and ZIP code (if it applies), necessary for VAT/tax calculation. The name, email, ZIP code, and the country are the only remaining address elements still mandatory. Note: Shoppers in the U.S., Puerto Rico, and Marshal Islands are required to provide a valid ZIP code for their location. The same requirement does not apply to shoppers worldwide.
  2. Not fill in the address information as the field is no longer mandatory. In fact, the address field doesn't need to be included in the cart design.

Billing address field

Mandatory

Comment

First name

Yes

Becomes part of the Name field

Last name

Yes

Becomes part of the Name field.

Address

No

-

City

Yes

Used for tax calculation. Shoppers from the U.S., Puerto Rico, Marshal Islands, Brazil, and Turkey are required to provide a valid city code for their location.

Zip or postal code

Yes*

Used for tax calculation. Shoppers from the U.S., Puerto Rico, Marshal Islands, and Brazil are required to provide a valid ZIP code for their location.

Country

Yes

Used for tax calculation.

State or province

Yes*

Used for tax calculation. Shoppers from the US, France, Romania, Brazil, Canada, India, and Turkey are required to provide their state or province during the checkout process.

Email

Yes

-

Confirm email

No

-
VAT Yes Used for tax calculation. Shoppers from Turkey, India, and Serbia are required to provide a valid VAT id during the checkout process.
Company Yes Used for tax calculation. Shoppers from Turkey and India are required to provide a valid company id.

ZIP validation

2Checkout performs checks designed to ensure that the ZIP code provided by customers is valid.

Tax calculation

Taxes are calculated after a valid ZIP code is provided, and if necessary, added to the value of the products in the cart.

FAQ

1. Is there any information included automatically for addresses?

A dash "-" is used for the address.

2. Does it work for trials?

Yes. SHORT_FORM is supported in scenarios in which your customers access trials for which they need to provide billing details and payment information.

3. Is it included in hash validation?

No. SHORT_FORM is not included when creating the hash for buy-links.

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.

Get in touch

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.

Contact sales Get Started
Verifone logo