Skip to main content

Search Orders

Overview

Use the searchOrders method via JSON-RPC API 6.0 to retrieve multiple orders depending on the filter parameters. 

Request Parameters

Parameter name Type Required/Optional Description
sessionID String Required Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.
orderSearchOptions Object Optional Use this object to configure your search order options.

Request Example

<?php

require ('PATH_TO_AUTH');

$orderSearchOptions = new stdClass();
$orderSearchOptions->StartDate = “2020-01-23”;
$orderSearchOptions->PartnerOrders = true;
$orderSearchOptions->Pagination = new stdClass();$orderSearchOptions->Pagination->Page = 2;
$orderSearchOptions->Pagination->Limit = 25;

try {
    $orders = $client->searchOrders($sessionID, $orderSearchOptions);
}
catch (SoapFault $e) {
    echo "orders: " . $e->getMessage();
    exit;
}

var_dump("orders", $orders);
               
?>

Response

A successful searchOrders call via JSON-RPC API 6.0 returns:

Parameter name Type Description
Items Array of Objects An array of Order Information objects, with catalog products or with dynamic products.
Pagination Object Pagination object with the following parameters: Page, Limit, Count.

 

Product

Overview

Use the Product object to create/add, update/edit and retrieve subscription plans/products for your account. You can control:

  • Product information
  • Pricing
  • Subscription plan settings and renewal configuration
  • Subscription plan recurring billing
  • Fulfillment
  • Shipping classes
  • Localization

 

Parameters Type/Description

Product

 

Object

AvangateId

Int

 

Unique, system-generated Avangate product ID. Read-only.

ProductCode

String

 

The product code that you can define for each of your offerings. Needs to be unique.

ProductType

String

 

REGULAR or BUNDLE

ProductName

String

 

The name of the product

ProductVersion

String

 

The product version number

GroupName

String

 

The name of the Product Group to which the product belongs. Cannot be edited as part of the addProduct call.

ShippingClass

Object

 

Existing shipping class object with the structure detailed below.

 

Name

String

 

 

The name of the shipping class

 

Amount

Decimal

 

 

The shipping costs

 

Currency

String

 

 

The currency ISO code used for shipping costs - ISO 4217.

 

ApplyTo

String

 

 

Possible values:

• PRODUCT

• ORDER

 

Type

Possible values:

• FIXED

• PERCENT

GiftOption

boolean

 

True or false depending on whether the product can be gifted or not.

ShortDescription

String

 

The product's short description

LongDescription

String

 

The product's long description

SystemRequirements

String

 

System requirements

ProductCategory

String

 

Product category

Platforms

Array of Platform objects

 

Array of objects detailing the platforms supported by the application. Details below.

 

PlatformName

String

 

 

The label of the platform per the product configuration.

 

Category

String

 

 

Platform category per product configuration. 

ProductImages

Array of Image objects

 

Image object. Details below. Read-only.

 

Default

Boolean

 

 

True or False depending on whether you set the image stored at the address in the URL parameter as default or not.

 

URL

String

 

 

The location of the image on the Avangate system.

TrialUrl

String (anyURI)

 

The URL from where shoppers can download trial software.

TrialDescription

String

 

Descriptive text entered for trials.

Enabled

Boolean

 

True/false depending on whether the products are active or disabled. When empty, Avangate marks the product as disabled.  

AdditionalFields

Array of AdditionalFieldAssigned objects

 

Array of existing additional fields assigned to products. Details below.

 

Label

String

 

 

The name of the additional field assigned to a product.

 

Code

String

 

 

The code of the additional field assigned to a product.

 

Enabled

Boolean

 

 

True or false depending on whether the assigned product field is enabled or not.

 

Required

Boolean

 

 

True or false depending on whether the assigned product field is required or not.

 

URLParameter

String

 

 

The value of the system generated URL parameter for the product field that can be used in Buy Links.

Translations

Array of ProductTranslation objects

 

Details below.

 

LongDescription

String

 

 

The translated long description in the language corresponding to the Translation object.

 

TrialUrl

String

 

 

The trial URL for users speaking the language corresponding to the Translation object.

 

TrialDescription

String

 

 

 

 

SystemRequirements

String

 

 

Localized system requirements.

 

Name

String

 

 

Localized product name.

 

Description

String

 

 

Localized product short description.

 

Language

String

 

 

ISO 639-1 two-letter code.

PricingConfigurations

Array of PricingConfiguration objects

 

Details below. Avangate creates pricing configurations during the process when you add a product.

 

Name

String

 

 

Pricing configuration name

 

Code

String

 

 

System-generated identifier.

 

Default

boolean

 

 

True for the default pricing configuration

 

BillingCountries

Array of strings

 

 

ISO codes of the countries assigned to the pricing configuration.

Empty unless specific countries are assigned to a pricing configuration.

 

PricingSchema

String

 

 

DYNAMIC – With a base price

FLAT – Without a base price

 

PriceType

String

 

 

Possible values:  NET / GROSS

 

DefaultCurrency

String

 

 

The ISO code of the default currency for the pricing configuration

 

Prices

Object

 

 

Details below.

 

Regular

Array of objects

 

 

Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.

 

Renewal

Array of objects

 

 

Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of PriceOptionCode objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.

 

PriceOptions

Array of AssignedPriceOptionGroup objects

 

 

Details below.

 

Code

String

 

 

System generated pricing options group code (you can also configure it) that the Avangate system uses to calculate product prices for pricing configurations without a base price.

 

Required

Boolean

 

 

True or False depending on whether you want to make it mandatory for shoppers to select the price option during the puyrchase process.

BundleProducts

Array of BundleProductCode objects

 

Details below.

 

ProductId

String

 

 

Unique, system-generated product ID.

 

ProductCode

String

 

 

Editable product code that you control.

Fulfillment

String

 

BY_AVANGATE

NO_DELIVERY – The Avangate system finalizes orders immediately after it receives payment confirmation.

BY_VENDOR – you are responsible for delivering/fulfilling orders

Prices

Array of Price objects

 

Use this object only when Pricing Configurations are not available for your account. Details below.

 

Amount

Int

 

 

The price of the product.

 

Currency

String

 

 

ISO code of the currency for the product price.

 

MinQuantity

Int

 

 

The minimum quantity of volume discounts. Default is 1.

 

MaxQuantity

Int

 

 

The maximum quantity of volume discounts. Default is 99999.

 

OptionCodes

Array of objects

 

 

Details below.

 

Code

String

 

 

Price option identifier.

 

Options

Array of strings

 

 

The pricing options group option code you configured that the Avangate system uses to calculate product prices for pricing configurations without a base price.

GeneratesSubscription

boolean

 

TRUE or FALSE depending on whether you set the product to generate subscriptions or not.

 

NULL for bundles for which you set the following subscription management option: “Use the subscription settings of each product in the bundle”

SubscriptionInformation

ProductSubscriptionInformation Object

 

Details below. NULL for bundles which you set to use the renewal settings of child products and not of the parent bundle.

 

DeprecatedProducts

Array

 

 

Deprecated products.

 

BundleRenewalManagement String

 

 

Possible values:

  • GLOBAL
  • INDIVIDUAL

Can be NULL.

 

BillingCycle

String

 

 

The number of subscription billing cycle units (months or days).  Possible values:

  • 0 (zero represents a one-time fee)

Days

  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14

 

Months

  • 1
  • 2
  • 3
  • 6
  • 12
  • 15
  • 18
  • 24
  • 36 (max)

 

BillingCycleUnits

String

 

 

The units of the billing cycle:

  • M - months

D - days

 

IsOneTimeFee

Boolean

 

 

True or False depending on whether the subscription is evergreen or not.

 

ContractPeriod

Object

 

 

Details below.

 

Period

Int

 

 

The contract period in months or days. -1 for unlimited contracts.

 

PeriodUnits

String

 

 

The contract period units

days | months

 

IsUnlimited

boolean

 

 

This flag is true if the contract is for an unlimited period

 

Action

String

 

 

The action performed after the subscription expires.

Possible values CANCEL | RESTART

 

EmailsDuringContract Boolean

 

 

True or False depending on whether you suppress renewal notification emails throughout the duration of the contract or not.

 

UsageBilling

Int

 

 

The usage billing interval must be smaller than or equal to the grace period.

 

Interval of time within the grace period, when the Avangate system attempts to automatically charge customers for recurring costs and additional metered usage fees (in arrears). Avangate renews subscriptions only after subscribers make all outstanding payments per the renewal settings (from the expiration or the renewal date). If automatic renewal and usage charges fail, subscriptions can be manually renewed only by the end of the grace period, after which they expire.

 

Can be NULL.

 

GracePeriod

Object

 

Type

String

 

 

CUSTOM – you configured grace period setting at product level.

GLOBAL – global grace period settings apply.

 

Period

String

 

 

Number of days set for the grace period.

 

PeriodUnits

String

 

 

D - Days.

 

IsUnlimited

Boolean

 

 

True or False depending on whether you set the grace peri2od to unlimited or not.

 

RenewalEmails

Object

 

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

Type 

String

 

 

GLOBAL - Send emails according to the global renewal notification settings.

CUSTOM – per product renewal notification settings

 

Settings

Object (can be NULL)

 

 

Details below.

 

ManualRenewal Object (can be NULL)

 

 

Details below.

 

Before30Days Boolean

 

 

True or False.

 

Before15Days Boolean

 

 

True or False.

 

Before7Days Boolean

 

 

True or False.

 

Before1Day 

Boolean

 

 

True or False.

 

OnExpirationDate Boolean

 

 

True or False.

 

After5Days

Boolean

 

 

True or False.

 

After15Days 

Boolean

 

 

True or False.

 

AutomaticRenewal

Object (can be NULL)

 

 

Details below.

 

Before30Days Boolean

 

 

True or False.

 

Before15Days Boolean

 

 

True or False.

 

Before7Days Boolean

 

 

True or False.

 

Before1Day 

Boolean

 

 

True or False.

 

OnExpirationDate 

Boolean

 

 

True or False.

 

After5Days

Boolean

 

 

True or False.

 

After15Days 

Boolean

 

 

True or False.

FulfillmentInformation

Object

 

Details below. Can be NULL. Available only in Product API 2.5 and later.

 

IsStartAfterFulfillment  Boolean

 

 

True or False. Depending on whether you want the subscription lifetime to start afther the completion of the fulfillment process or not.

 

IsElectronicCode 

Boolean

 

 

True or False. Depending on whether you configure the delivery of keys/codes for the product or not.

 

IsDownloadLink 

Boolean

 

 

True or False. Depending on whether you configure the delivery of a product file or not.

 

IsBackupMedia 

Boolean

 

 

True or False. Depending on whether you configure the delivery of backup media or not.

 

IsDownloadInsuranceService Boolean

 

 

True or False. Depending on whether you enable the Download Insurance Service or not, for a product for which you configure a product file.

 

IsInstantDeliveryThankYouPage Boolean

 

 

True or False. Depending on whether you enable instant delivery in the Thank You page or not.

 

IsDisplayInPartnersCPanel Boolean

 

 

True or False. Depending on whether you share access to the product file with your channel partners or not.

 

CodeList 

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

The unique code list identifier.

 

Name 

String

 

 

Name of the code list.

 

Type 

String

 

 

Code list type:

  • STATIC

DYNAMIC

 

BackupMedia 

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

The unique backup media identifier.

 

Name 

String

 

 

Name of the backup CD/DVD.

 

Type 

String

 

 

Media type:

CD

 

ProductFile

Object (can be NULL)

 

 

Details below.

 

Code 

String

 

 

Unique product file identifier.

 

Name 

String

 

 

Display name.

 

File 

String

 

 

Name of the product file.

 

Version 

String

 

 

File version.

 

Size

String

 

 

File size.

 

Type 

String

 

 

File type.

 

LastUpdate 

String

 

 

YYYY-MM-DD HH-MM-SS. Date time stamp when you last updated the file.

 

AdditionalInformationByEmail String (can be NULL)

 

 

The text you set up in the Additional fulfillment information - by email area.

 

AdditionalInformationEmailTranslations Object (can be NULL)

 

 

Array of localized Additional fulfillment information - by email texts.

 

AdditionalThankYouPage String (can be NULL)

 

 

The text you set up in the Additional fulfillment information - "Thank you" page area.

 

AdditionalThankYouPageTranslations Array (can be NULL)

 

 

Array of localized Additional fulfillment information - "Thank you" page texts.

 

 

Dynamic pricing

Overview

Dynamic pricing (with base price) is a basic charge configuration. 2Checkout supports both one-time and recurring dynamic pricing, and offers the possibility to control various cost components through product options pricing. 

Examples:

  • A $99.99 recurring, annual anti-malware subscription.
  • A recurring, monthly $20 subscription to a service providing credit score information.
  • A flat, one-time fee of $1,000 for the license to a CRM software. 



If the pricing configuration has a base price but the customer should be able to alter it by choosing from product options (like subscription types, number of users, platforms), then enter a base price and choose between Net and Gross price type. Extra pricing options can be dynamically added after the product is added, based on formulas from the 2Checkout system.

Availability

All 2Checkout accounts. 

Requirements

Create at least a product/subscription plan before defining pricing. 

Type

  • Net: without taxes - 2Checkout applies extra taxes to the default price, such as Tax/VAT for US/EU orders during  the ordering process. 
  • Gross: with taxes included - 2Checkout takes the taxes out of the costs paid by shoppers, without modifying the price during the ordering process. 

Currency

When defining product prices you can:

  1. Configure the price only for the default currency - 2Checkout converts amounts in the cart based on the currency selected by/for shoppers. Currency rates are available here: https://secure.2checkout.com/content/...p?CURRENCY=USD

    This is an XML schema with the corresponding values for the other currencies compared to the one supplied in the CURRENCY query parameter.

  2. Specify prices in all currencies available for your account - 2Checkout serves shoppers the prices for all the currencies you set up without converting the amounts. 

Basic setup

You can set up basic pricing when first defining your product and then edit the charge configuration as well as utilize advanced charge capabilities. 

 

  1. Choose the default currency, select the base price option and enter the product price.
  2. After filling in the base price for your product, you can:
    • Let the 2Checkout platform auto convert it to other currencies during the ordering process;
    • Manually set the price for each currency.
  3. If you choose to manually enter the price for some currencies only, then 2Checkout automatically converts the ones you left blank from the default currency during the ordering processing.
  4. Extra taxes may be applied to the base price during the ordering process, such as VAT for EU orders, or sales tax for the US. You can choose not to have country specific taxes added to the price in the shopping cart by selecting with taxes included (Gross). This means that the country specific tax fees will be pulled from the product price during ordering process. With the Net option, the 2Checkout system will charge shoppers VAT and sales taxes, when these apply, in addition to the price of the product, and deal with tax management on your behalf. 

Advanced setup

Access advanced pricing/charge options by editing product and navigating to the Pricing tab. This area enables you to edit and create pricing configurations and create charge models that include:

  • Volume pricing
  • Custom recurring charges
  • Advanced pricing options
  • Pay-per-use (Metered billing)
  • Tiered charges

Track affiliate traffic with custom parameters

Overview

If you are using our Avangate Affiliate Network it's important to understand the details related to the quality and potential of the traffic generated by your affiliates.

To monitor and analyze the affiliate-referred traffic, you might be using any analytics tools such as Google Analytics, and/or Adobe Analytics, but not only. Now you can do this by using any type of parameters you want, including, but not only, UTM parameters. These are automatically parsed by both Google Analytics and Adobe Analytics, so you are able to populate standard and custom analytics reports. 

Availability

Available upon request to merchants using the Avangate Affiliate Network.

Benefits

  • Full flexibility in defining the name and the value of the parameters (both static and dynamic)
  • Easy integration with Google/ Adobe Analytics or any other analytics tool merchants use
  • No need for affiliates to perform additional actions when generating new links
  • No need for affiliates to change previously generated links

Workflow

If you are using an affiliate network (including Avangate Affiliate Network) and you want to understand the type of users each network brings, as well as analyze the traffic crossing between affiliates (using Google Analytics or any other analytics tool) you can easily set up any type of parameters, including UTM (Universal Tag Manager) parameters.

  1. Log into your Merchant Control Panel.
  2. Navigate to Affiliate network → Settings.
  3. Click on the Tracking settings tab to define custom parameters.
  4. Click on Add parameter to add the static or dynamic parameters that will be used to identify traffic generated by all networks (e.g. utm_source and utm_medium).

List of parameters_1.png

5. Input the parameter Name and Value (e.g. utm_source = AVAffiliate, utm_medium = AffiliateID), and click on Save changes.

Add a parameter.png

6. To modify a parameter, go to the list of Available parameters and click on the Edit button in the column Actions. 

7. Then click on Save changes.

Edit a parameter.png

Affiliate links triggering merchant website/landing page will be available through the above set parameters via any analytics tool.

Affiliate links triggering cart/product pages will populate these parameters in the omniture parameter collection (that can be easily integrated with either Google Analytics or any other analytics tool).

The omniture_vars Object

The 2Checkout shopping cart pages use an object called omniture_vars, which contains a variety of parameters that offer information about the particularities of the cart and the products in it. The object can be accessed by typing “omniture_vars” in the browser console.

The object contains detailed information about the products in the cart (examples: product name, id, price, product group, pricing options, whether the product is an upsell or a cross-sell, etc.), as well as information about the configuration of the shopping cart, such as cart currency, language, the selected country, the id of the template used, whether the cart flow has a review page, whether the cart is in test mode, or whether the cart link is generated by a 2Checkout affiliate.

The values of the parameters in the omniture_vars object are updated when the page refreshes. For example, if the currency is changed in the cart, the page refreshes and the omniture_vars object is updated with the new value for the currency.

Parameters from omniture_vars can be used for custom tracking, for example for sending custom dimensions data to Google Analytics with specific information about the cart configuration.

Reducing churn through online retention strategies

Overview

A common pitfall throughout the eCommerce landscape is represented by focusing on customer base growth at the expense of neglecting existing customers. While growing your customer base is key to a business's success, customer retention is equally important, especially from a financial standpoint. One of the most frequent mistakes businesses do in terms of customer retention is ignoring the customers once they brought them on board.

Analyzing customer data from hundreds of companies in our portfolio, we’ve concluded that shoppers are much more invested in continuing their subscriptions when approached through proactive retention strategies. As a result, online renewals proved to be more than twice as effective as offline ones, while automatic renewals saved three times more subscriptions than manual ones.



While developing your retention subscriber retention strategy, make sure to clearly inform your users about the incurred charges and billing cycles, and give them the ability to easily cancel automatic renewals, should they not need them. Keep in mind that placing your customers in control of their subscription management process is paramount to preventing and reducing your refunds and/or chargeback rates.

2Checkout’s retention tools introduce a smart and easy way to reduce customer churn and gain useful insights about what drives customers to cancel automatic renewals. Use 2Checkout’s out of the box retention capabilities to:

  • Leverage proactive subscription enrollment to increase renewals and generate additional revenue. Use special deals to deepen loyalty and incentivize your customers to enroll in automatic subscription renewals.
  • Decrease churn and prevent recurring revenue from “leaking” by converting cancelations into continued subscriptions. Offer the right incentives to the customers that decided to cancel their subscriptions and make them change their mind at the point of exit.
  • Turn threats into opportunities by capturing your customers’ feedback at the point of cancelation.

Auto-renewal enrollment

If your customers purchased subscriptions from you and disabled the automatic renewal upon purchase, try to convert them to a recurring billing plan. An easy way to increase your revenue and customer retention rate is by proactively incentivizing your customers to enroll in auto-renewal campaigns. Do this via 2Checkout’s retention tools and configure discounts for one or multiple billing cycles. Your customers see the discounts in 2Checkout myAccount and they can quickly enable automatic renewal from their account.

Important: 2Checkout triggers auto-renewal enrollment campaigns only for products/subscriptions paid for with online payment methods.

2Checkout recommendations

Based on existing auto-renewal enrollment campaigns, 2Checkout recommends starting with a 15% discount for one billing cycle.

2Checkout vendors have successfully configured proactive enrollment campaigns offering discounts from 15% up to 25% for one billing cycle. This ultimately led to increases in sales of up to three times the value of the awarded discounts without counting the entire customer lifecycle value.

We recommend testing such campaigns for specific products with different time intervals and with different tiers of discounts. This way you can choose the best discounts for your customers and increase revenue and their lifetime value.

Behavior

Use promotions to enroll your customers in auto-renewal campaigns by leveraging 2Checkout myAccount. Your customers will see campaign teasers such as the one below.

Churn prevention

Subscribers enrolled in auto-renewal campaigns are 3.5 times more likely to continue their subscriptions. Churn prevention tools help you prevent recurring revenue from “leaking” by converting terminations into continued subscriptions.

2Checkout gives you an easy way to configure churn prevention campaigns so that you can:

  • Engage and collect feedback from your churning subscribers to optimize your products, marketing campaigns, and business operations. You can extract valuable information from cancellation reasons, such as pricing, feature ideas, competitor information, or just service quality improvements.
  • Solidify your recurring revenue by offering discounts to customers who want to cancel recurring billing, incentivizing them to keep auto-renewal enabled for their subscriptions.

2Checkout recommendations

Based on existing churn prevention campaigns, 2Checkout recommends asking for customer feedback and subsequently offers a 15% to 35% discount for one billing cycle. This configuration ultimately led to an increase in recovered volumes of more than 4 times the value of the awarded discounts, not considering the entire customer lifecycle value.

Behavior

Once you've started the campaign, your shoppers are notified in myAccount whenever they try to stop subscription auto-renewals for the products included in the campaign. You can customize the message displayed to your shoppers and choose whether or not to gather feedback.

The first pop-up displays either the default message shown below or the one you customize.

The next pop-up asks for a cancellation reason and shopper feedback (if you choose to gather it).

The last pop-up shows the discount that you offered for keeping the auto-renewal.

Should customers accept your discount, 2Checkout renews the subscription at the specified discounted price and improves your churn rate.

Conclusion

2Checkout’s retention tools are a key feature in increasing your revenue and customer lifetime value through customer incentives. At the same time, they can help you get important insights on how your customers see your products, what they love and/or dislike about them and what you can do to stay competitive.

Make sure you configure retention campaigns and test multiple scenarios. Different customers have different needs, so they might react differently to unique discounts. Incentivize them to keep their subscriptions active and fine-tune your retention campaigns for maximum impact on your revenue and churn rate.

Import usage from CSV

Overview

Upload usage data through the 2Checkout API from a CSV (comma-separated values) file. 2Checkout will capture the parameters sent and import the usage data into the system. Once the upload process is complete, you'll be able to access the uploaded file in the Usage area of the Merchant Control Panel.

Use the importUsageFromCsv method via SOAP APIv6 to upload usage from a CSV file.

Set the DATE parameter to GMT+2 time zone, when making the API call to the Usage Upload endpoint.

Method and URL

POSThttps://api.2checkout.com/subscription/payperusage/receiver/index.php

Parameters

Parameters

Type

Required/Optional

Description

Used in HASH validation*

merchant

String

Required

Your unique 2Checkout merchant code. View merchant code.

YES

secret_key

String

Required

The secret key associated to your account. View secret key.

YES

file_MD5

String

Required

The md5 hash of the CSV file used to upload usage.

YES

hash

String

Required

The MD5 hmac key for the request.

N/A

UsageStart Datetime Required The datetime when the usage started; can be the same as UsageEnd. For existing records, this will be updated to time 00:00:00. N/A
UsageEnd Datetime Required The datetime when the usage ended and was recorded.  For existing records this will be updated to time 23:59:59, this will be enforced in the CSV upload as well. N/A
OptionCode String Required Unique codes you provided as identifiers of specific Pricing Options in the Usage Scale Pricing Options Group scheme. Example: metered pricing.   N/A
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. N/A
SubscriptionRef String Required Unique code that represents a subscription. Example: 83FE4FEF2. N/A

Request Example

<?php
//hmac
$date             = date("Y-m-d");
$fileReceived_md5 = md5_file("[Path to the CSV file used for usage upload]");
$merchantCode     = "";
/* 2Checkout Code */
$merchantKey      = "";
/* Merchant Secret Key */
$hashParams       = "MERCHANT={$merchantCode}&FILE={$fileReceived_md5}&DATE={$date}";
$hmac             = hash_hmac('md5', $hashParams, $merchantKey);
?>

<html>
<body>
<form method="post" action="https://api.2checkout.com/subscription/payperusage/receiver/index.php" enctype="multipart/form-data">
<input type="text" name="MERCHANT" value="<?php
echo $merchantCode;
?>" /><br />
<input type="text" name="HASH" value="<?php
echo $hmac;
?>" /><br />
<input type="file" name="OPTIONS" /><br />
<input type="hidden" name="FILE_MD5" value="<?php
echo $fileReceived_md5;
?>" />
<input type="hidden" name="DATE" value="<?php
echo $date;
?>" />
<input type="submit" /><br />
</form>
</body>
</html>

Error handling

Message code

Message description

Resolution

1

The upload operation completed successfully.

N/A

Invalid account!

The merchant code provided does not belong to a vendor in the 2Checkout system.

Please check your merchant code and make sure you're using the correct version. View merchant code.

Bad signature on the received file!

The upload CSV file's md5 signature is different than the one sent as a parameter.

Please make sure that you're using the correct md5 signature for the CSV file, or that you're uploading the CSV file for which the signature was generated.

Invalid signature

The HMAC calculated by the 2Checkout system is different from the one you're sending.

Please make sure that all parameters use correct values.

Remove promotion sources

Overview

Use the deletePromotionSources method to define new sources for an existing promotion.

Parameters

Parameter Type/Description

sessionID

Required (string)

 

Output of the Login method.

promotionCode

Required (string)

 

The code corresponding to the promotion that you want to remove sources from.

promotionSources

Required (string array)

 

Array of strings defining the promotion sources to be removed.

Response

Parameter Type/Description

status

Boolean

 

True or false

Request

<?php

function callRPC($Request, $host, $Debug = true) {
    $curl = curl_init($host);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($curl, CURLOPT_VERBOSE, true);
    curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($curl, CURLOPT_SSLVERSION, 0);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $RequestString);
    if ($Debug) {
        $RequestString;
    }
    $ResponseString = curl_exec($curl);
    if ($Debug) {
        $ResponseString;
    }
    if (!empty($ResponseString)) {
        var_dump($ResponseString);
        $Response = json_decode($ResponseString);
        if (isset($Response->result)) {
            return $Response->result;
        }
        if (!is_null($Response->error)) {
            var_dump($Request->method, $Response->error);
        }
    } else {
        return null;
    }
}

$host = 'https://api.avangate.com/rpc/3.1/';

$merchantCode = "YOUR_MERCHANT_CODE"; // your account's merchant code available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY"; // your account's secret key available in the 'System settings' area of the cPanel: https://secure.avangate.com/cpanel/account_settings.php

$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);

$i = 1;

$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;

$sessionID = callRPC($jsonRpcRequest, $host);

// Promotion code corresponding to the promotion you want to remove sources from
$promotionCode = '';

// Sources array with the source values 
$sources = ['source1', 'source2'];

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'deletePromotionSources',
'params' => array($sessionID, $promotionCode, $sources)
);
var_dump (callRPC($jsonRpcRequest, $host));

Order field

Overview

Use this object to retrieve information about additional order/product fields. 

Parameters

AdditionalField

Object

Label

String

 

Field text.

Code

String

 

Field identifier. Alpha-numeric chars, underscores and dashes.

Type

String

 

Field type:

  • LISTBOX
  • CHECKBOX
  • TEXT
  • HIDDEN

ApplyTo

Sting

 

  • ORDER
  • PRODUCT

Values

Array of values

 

Custom values you control.

ValidationRule

String

 

The validation rule restricting the type of information shoppers can enter in the additional field during the purchase process.

Translations

Array of objects

 

Details below.

 

Translation

Object

Label

String

 

Field text translated in the language of the Translations object.

Values

Object

 

Custom values you control translated in the language of the Translations object.

Language

String

 

ISO language code. (ISO 639-1 two-letter code).

 

Add a pricing configuration

Overview

Use the addPricingConfiguration method to add a new pricing configuration for your account.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect.  The sessionID expires in 10 minutes.

PricingConfiguration

Required (object)

 

Use this object to add a new pricing configuration for your account.

ProductCode

Required (string)

 

The code of the produt you assign the configuration to.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$PricingConfiguration = new stdClass();
$PricingConfiguration->Default = True;
$PricingConfiguration->Name = 'New Pricing Configuration Through API';
$PricingConfiguration->BillingCountries = array();
$PricingConfiguration->BillingCountries[0] = 'RO';
$PricingConfiguration->BillingCountries[1] = 'DE';
$PricingConfiguration->PricingSchema = 'DYNAMIC';
$PricingConfiguration->PriceType = 'NET';
$PricingConfiguration->DefaultCurrency = 'USD';
$PricingConfiguration->Prices = new stdClass();
$PricingConfiguration->Prices->Regular = array();
$PricingConfiguration->Prices->Regular[0] = new stdClass();
$PricingConfiguration->Prices->Regular[0]->Amount = 69.09;
$PricingConfiguration->Prices->Regular[0]->Currency = 'USD';
$PricingConfiguration->Prices->Regular[0]->MinQuantity = 1;
$PricingConfiguration->Prices->Regular[0]->MaxQuantity = 35;
$PricingConfiguration->Prices->Regular[0]->OptionCodes = array();
$PricingConfiguration->Prices->Regular[0]->OptionCodes[0] = new stdClass();
$PricingConfiguration->Prices->Regular[0]->OptionCodes[0]->Code = 'G77ICHEM1C';
$PricingConfiguration->Prices->Regular[0]->OptionCodes[0]->Options = array();
$PricingConfiguration->Prices->Regular[0]->OptionCodes[0]->Options[0] = 'zh5onfolw7';
$PricingConfiguration->Prices->Regular[0]->OptionCodes[0]->Options[1] = '75rjldfcnz';
$PricingConfiguration->Prices->Regular[0]->OptionCodes[1] = new stdClass();
$PricingConfiguration->Prices->Regular[0]->OptionCodes[1]->Code = 'BAWAQB8LZP';
$PricingConfiguration->Prices->Regular[0]->OptionCodes[1]->Options = array();
$PricingConfiguration->Prices->Regular[0]->OptionCodes[1]->Options[0] = 'r3oi06opvi';
$PricingConfiguration->Prices->Regular[0]->OptionCodes[1]->Options[1] = '76gqbq4bhd';
$PricingConfiguration->Prices->Regular[1] = new stdClass();
$PricingConfiguration->Prices->Regular[1]->Amount = 64.66;
$PricingConfiguration->Prices->Regular[1]->Currency = 'USD';
$PricingConfiguration->Prices->Regular[1]->MinQuantity = 36;
$PricingConfiguration->Prices->Regular[1]->MaxQuantity = 83;
$PricingConfiguration->Prices->Regular[1]->OptionCodes = array();
$PricingConfiguration->Prices->Regular[1]->OptionCodes[0] = new stdClass();
$PricingConfiguration->Prices->Regular[1]->OptionCodes[0]->Code = '8RNXV3T3RE';
$PricingConfiguration->Prices->Regular[1]->OptionCodes[0]->Options = array();
$PricingConfiguration->Prices->Regular[1]->OptionCodes[0]->Options[0] = 'rorqkqnd9p';
$PricingConfiguration->Prices->Regular[1]->OptionCodes[0]->Options[1] = 'aeu89gqdg6';
$PricingConfiguration->Prices->Regular[1]->OptionCodes[1] = new stdClass();
$PricingConfiguration->Prices->Regular[1]->OptionCodes[1]->Code = 'DJYD713MKC';
$PricingConfiguration->Prices->Regular[1]->OptionCodes[1]->Options = array();
$PricingConfiguration->Prices->Regular[1]->OptionCodes[1]->Options[0] = 'y2z2squ7c1';
$PricingConfiguration->Prices->Regular[1]->OptionCodes[1]->Options[1] = 'g74qfskbjg';
$PricingConfiguration->Prices->Renewal = array();
$PricingConfiguration->Prices->Renewal[0] = new stdClass();
$PricingConfiguration->Prices->Renewal[0]->Amount = 7.89;
$PricingConfiguration->Prices->Renewal[0]->Currency = 'USD';
$PricingConfiguration->Prices->Renewal[0]->MinQuantity = 84;
$PricingConfiguration->Prices->Renewal[0]->MaxQuantity = 100;
$PricingConfiguration->Prices->Renewal[0]->OptionCodes = array();
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[0] = new stdClass();
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[0]->Code = '73QCSXYH0E';
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[0]->Options = array();
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[0]->Options[0] = '54xu7mngqm';
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[0]->Options[1] = 'p6m8im2unl';
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[1] = new stdClass();
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[1]->Code = '0QD0CF0OIE';
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[1]->Options = array();
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[1]->Options[0] = 'ytbac9wpmh';
$PricingConfiguration->Prices->Renewal[0]->OptionCodes[1]->Options[1] = 'lpkxxqsqxb';
$PricingConfiguration->Prices->Renewal[1] = new stdClass();
$PricingConfiguration->Prices->Renewal[1]->Amount = 76.99;
$PricingConfiguration->Prices->Renewal[1]->Currency = 'USD';
$PricingConfiguration->Prices->Renewal[1]->MinQuantity = 101;
$PricingConfiguration->Prices->Renewal[1]->MaxQuantity = 544;
$PricingConfiguration->Prices->Renewal[1]->OptionCodes = array();
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[0] = new stdClass();
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[0]->Code = '03APF0H4QF';
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[0]->Options = array();
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[0]->Options[0] = '15ce5uw2j6';
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[0]->Options[1] = 'e88d5hk0tb';
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[1] = new stdClass();
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[1]->Code = 'PT00TYI2VY';
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[1]->Options = array();
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[1]->Options[0] = '10c24smlbl';
$PricingConfiguration->Prices->Renewal[1]->OptionCodes[1]->Options[1] = '0ondbwdk3q';
$PricingConfiguration->PriceOptions = array();
$PricingConfiguration->PriceOptions[0] = new stdClass();
$PricingConfiguration->PriceOptions[0]->Code = 'FKQ8CFLYKM';
$PricingConfiguration->PriceOptions[0]->Required = false;
$PricingConfiguration->PriceOptions[1] = new stdClass();
$PricingConfiguration->PriceOptions[1]->Code = 'TH1HKFOTFR';
$PricingConfiguration->PriceOptions[1]->Required = true;

$ProductCode= 'API_Imported_123456';

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'addPricingConfiguration',
'params' => array($sessionID, $PricingConfiguration, $ProductCode) //Use product ID and not product code for API versions 2.3 and earlier
);

var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

Require end user information

Overview

Make it mandatory for your partners to attach end user information to orders.

You can also attach end user information on behalf of your partners.

Important

When you enable this feature/require end user information, 2Checkout will fulfill/deliver orders only after the mandatory details are provided. When supplied by either you or your partners, required end user details trigger the finalization of purchases and orders reach the Complete status.

Requirements

You need to configure at least one electronic delivery codes list, either static or dynamic to use this feature. You can manage code lists in the Electronic Delivery page.

How does this feature work?

When enabled, this feature makes end user information a requirement, and introduces a mandatory stage in the ordering process. End user information needs to be supplied by you, your partners or the end users for the orders to be fulfilled/delivered and reach the Complete status. Once attached, end user info is used for the details of the Customer entity created for each subscription.

  1. Attach end user info AFTER placing the order
    • Manually for each license/subscription.
    • Via CSV (comma separated values) upload.
    • Send a registration email to customers and let them enter the end user information themselves.
  2. Attach end user info BEFORE placing the order
    • Manually for each license/subscription.
    • Via a CSV (comma separated values) file.

Partners have to provide the necessary details to push the order to the delivery/fulfillment stage, but you can also provide the details if you have them.

Alternatively, fulfillment can be done exclusively to partners, leaving them to deal with their customers, and in this case, no additional info is required.

When the system configuration is set to distribute products/keys to end users, customers are required to first register ahead of delivery/fulfillment.

Enable this feature

To require end user information for each order:

  1. Go to:
    • The Partners area of the Control Panel if you're enabling the feature for a single reseller.
    • The Partnership programs area of the Control Panel if your enabling the feature for a group of resellers governed by the same partner program.
  2. Search for and edit:
    • A specific partner.
    • A partner program.
  3. Select the Commercial settings tab in either area.
  4. Scroll down to the Delivery settings area.
  5. Check the Requires end user information option under Codes Delivery.
  6. Select the After placing the order option to make end user information mandatory after orders are placed.
  7. Select the Before placing the order option to make end user information a mandatory stage of the ordering process.
  8. Orders are fulfilled/delivered and reach the Complete status only if end user information is attached.

Attaching end user information

Both you and your partners can add end user information after placing orders. End user information needs to be attached to the placed order for the 2Checkout system to fulfill/deliver it, otherwise, the order will not reach the Complete status.

Additionally, you can now identify end users/customers by the ‘customer external ID’ information in the listing results of the license report, without having to generate and open a CSV file. 

Manually

To attach end user information, follow the steps below.

  1. Go to Partner orders.
  2. Search for and Edit an order.
  3. Scroll down to the bottom of the screen in the View Order page.
  4. Click Add now.
  5. Fill in all required info in the End user details.
  6. Click Save.

The end user details provided will also be copied to the customer information associated with the subscription.

CSV upload

As an alternative to manually attaching end user information to orders, you can upload CSV files with the desired details. Follow the steps below to do this.

  1. Go to Orders & customers -> Partner orders
  2. Search for an order.
  3. Scroll down to the bottom of the screen in the View Order area.
  4. Click Upload end user information in a .CSV file.
  5. Download the .CSV template provided.
  6. Fill in the end user details. It's very important that you do not modify the headers of the document template available for download, either by altering the text or by changing their order to ensure that the information will be introduced correctly into the system. Be advised that the CSV templates are each tailored (containing the 2Checkout license/subscription references) to the specific order for which you're downloading them.
  7. Upload the .CSV file.

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.

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.

Verifone logo