Skip to main content

Set SKU codes

Overview

Use the setSku method to create a valid combination of elements (code) for a specific product. 

In case there is an active SKU schema available for that Product Code and Pricing Configuration Code, when setting new SKUs the entire existing schema will be overwritten with the new values. The same validations that are applied to the CSV file import in the Merchant Control Panel are applicable to the API as well.

Product SKUs created via API will also be available in the Merchant Control Panel for manual update (Dashboard → Setup → Products → Edit product → Information → SKU Manager (SKU list Tab).

Request Parameters

Parameters Required Type/Description
     
     
     
     

Request

<?php

require ('PATH_TO_AUTH');

$product = new \stdClass();
$product->ProductCode = "6B3CB17DDA_COPY1";

$skuPricingOption1 = new \stdClass();
$skuPricingOption1->Code = "E684EC99B0";

$skuDetail1 = new \stdClass();
$skuDetail1->ProductSKU = "Product_Test_SKU_001022";
$skuDetail1->Currency = "USD";
$skuDetail1->FromQty = 1;
$skuDetail1->ToQty = 3
$skuDetail1->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 1";
$skuGroupOption->Value = "option_code_1";

$skuGroup->Options = [$skuGroupOption];

$skuDetail1->Groups = [$skuGroup];
$skuDetail1->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrlXauuZOojh8cww==";

$skuDetail2 = new \stdClass();
$skuDetail2->ProductSKU = "Product_Test_SKU_001023";
$skuDetail2->Currency = "USD";
$skuDetail2->FromQty = 1;
$skuDetail2->ToQty = 3
$skuDetail2->PurchaseType = "NEW_PRODUCT";

$skuGroup = new \stdClass();
$skuGroup->GroupCode = "GRUP_1";

$skuGroupOption = new \stdClass();
$skuGroupOption->Name = "option name 2";
$skuGroupOption->Value = "option_code_2";

$skuGroup->Options = [$skuGroupOption];

$skuDetail2->Groups = [$skuGroup];
$skuDetail2->Options = "eJwBLADT/6G10uOW07exk6mNk7KvrpaSc4l1lbXToqi5sriTcbOXseWu3ZGrmXauuZOojjccxw==";

$skuPricingOption1->Details = [$skuDetail1, $skuDetail2];

$product->SkuPricingOptions = [$skuPricingOption1];

$jsonRpcRequest = array (
    'method' => 'setSku',
    'params' => array($sessionID, [$product]),
    'id' => $i++,
    'jsonrpc' => '2.0'
);

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

Response Parameters

Parameters Required Type/Description
     
     
     
     
     

Response

class stdClass#7 (3) {
  public $ProductCode =>
  string(16) "6B3CB17DDA_COPY1"
  public $PricingConfigurations =>
  array(1) {
    [0] =>
    class stdClass#8 (6) {
      public $Code =>
      string(10) "E684EC99B0"
      public $Currencies =>
      array(1) {
        [0] =>
        class stdClass#9 (1) {
          public $Code =>
          string(3) "EUR"
        }
      }
      public $PurchaseTypes =>
      array(1) {
        [0] =>
        class stdClass#10 (1) {
          public $Code =>
          string(7) "RENEWAL"
        }
      }
      public $QuantityIntervals =>
      array(0) {
      }
      public $PriceOptionGroups =>
      array(0) {
      }
      public $SkuCollection =>
      array(1) {
        [0] =>
        class stdClass#11 (2) {
          public $ProductCode =>
          string(16) "6B3CB17DDA_COPY1"
          public $SkuPricingOptions =>
          array(1) {
            [0] =>
            class stdClass#12 (3) {
              public $Code =>
              string(10) "E684EC99B0"
              public $Details =>
              array(8) {
                [0] =>
                class stdClass#13 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008899"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#14 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#15 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78164;}}"
                }
                [1] =>
                class stdClass#16 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008902"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#17 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#18 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(6) "a:0:{}"
                }
                [2] =>
                class stdClass#19 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008900"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#20 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#21 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78165;}}"
                }
                [3] =>
                class stdClass#22 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008901"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(1)
                  public $ToQty =>
                  int(3)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#23 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#24 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78166;}}"
                }
                [4] =>
                class stdClass#25 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008907"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#26 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#27 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78164;}}"
                }
                [5] =>
                class stdClass#28 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008910"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#29 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#30 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(6) "a:0:{}"
                }
                [6] =>
                class stdClass#31 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008908"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#32 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#33 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78165;}}"
                }
                [7] =>
                class stdClass#34 (7) {
                  public $ProductSKU =>
                  string(23) "Product_Test_SKU_008909"
                  public $Currency =>
                  string(3) "EUR"
                  public $FromQty =>
                  int(4)
                  public $ToQty =>
                  int(7)
                  public $PurchaseType =>
                  string(7) "RENEWAL"
                  public $Groups =>
                  array(1) {
                    [0] =>
                    class stdClass#35 (2) {
                      public $GroupCode =>
                      string(6) "GRUP_2"
                      public $Options =>
                      array(1) {
                        [0] =>
                        class stdClass#36 (2) {
                          public $Name =>
                          string(6) "grup 2"
                          public $Value =>
                          string(13) "option_code_4"
                        }
                      }
                    }
                  }
                  public $Options =>
                  string(32) "a:1:{i:16885;a:1:{i:0;i:78166;}}"
                }
              }
              public $Errors =>
              array(0) {
              }
            }
          }
        }
      }
    }
  }
  public $Errors =>
  array(0) {
  }
}

Search upsell campaigns

Overview

Use the searchUpsellCampaigns method via JSON-RPC API 6.0 to find and filter specific upsell campaigns.

Request Parameters

Parameter Name Type Required/Optional Description

SessionId

String

Required

Unique 2Checkout session ID code.

Name

String

String

Title of the campaign.

PrimaryProductCodes

Array of Strings

Optional

Array of product codes used as primary products you want to filter by.

 PrimaryProductCode

String

Optional

Unique product code.

RecommendedProductCodes

Array of Strings

Optional

Array of product codes used as recommended products you want to filter by.

 RecommendedProductCode

String

Optional

Unique product code.

Statuses

Array of Strings

Optional

Array of statuses you want to filter by.

 Status

String

Optional

Status of the upsell campaign. Enum can be one of:

 

  • Enabled
  • Disabled
  • Expired

StartsAfter

String

Optional

Date in ‘Y-m-d’ format after which campaigns start.

StartsBefore

String

Optional

Date in ‘Y-m-d’ before campaigns start.

EndsAfter

String

Optional

Date in ‘Y-m-d’ after which campaigns are ending.

EndsBefore

String

Optional

Date in ‘Y-m-d’ before campaigns end.

EnabledForRenewals

Boolean

Optional

Filter campaigns enabled for renewal.

CampaignCodes

Array of Strings

Optional

Array of campaign codes to filter by.

 CampaignCode

String

 

Unique code for an upsell campaign.

Page

Integer

Optional

Page you want to retrieve.

Limit

Integer

Optional

Maximum number of campaigns per page.

Request Example

<?php
 
require ('PATH_TO_AUTH');
 
$filters = new \stdClass();
$filters->Name = 'op_2';
$filters->PrimaryProductCodes = ['A59VUKFMA2', 'JN2GSQ184L'];
$filters->RecommendedProductCodes = ['XI2MNQ41MNH'];
$filters->Statuses = ['DISABLED', 'EXPIRED'];
$filters->StartsBefore = '2020-10-01';
$filters->StartsAfter = '2019-11-05';
$filters->EndsBefore = '2022-11-10';
$filters->EndsAfter = '2020-10-02';
//$filters->EnabledForRenewals = true;
//$filters->CampaignCodes = ['8050a1b7-338e-45bd-9936-17f98b01349e'];
$filters->Page = 1;
$filters->Limit = 10;
 
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'searchUpsellCampaigns';
$jsonRpcRequest->params = array($sessionID, $filters);
$jsonRpcRequest->id = $i++;
 
try {
    $result = callRPC($jsonRpcRequest, $host);
    echo "Campaigns: </br>",
    var_dump($result);
}
catch (SoapFault $e) {
    echo "Could not fetch upsell campaigns: " . $e->getMessage();
    exit;
}

Response

Parameter Name Type Required/Optional Description

Page

Integer

Required

The Search page you are on.

Limit

Integer

Required

Maximum number of campaigns per page.

Upsells

Array of Strings

Required

Array of Upsell Campaigns.

   UpsellCampaign

Object

Required

 

UpsellsCount

Integer

Required

Total number of Upsells that fit your search criteria.

PagesCount

Integer

Required

Total number of pages with Upsells that fit your criteria.

 

Search Orders

Overview

Use the searchOrders method via SOAP 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 SOAP 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.

 

Selling restrictions

Per-product selling restrictions

2Checkout enables you to take advantage of functionality designed to restrict the sales of products in specific markets or for certain payment methods.

Essentially, you can limit product sales into:

  • A specific country
  • Multiple countries

At the same time, you can block product sales that involve

  • A specific payment method
  • Multiple payment methods

Reasons for restrictions vary but can include the need to adhere to the applicable laws, regulations, controls, policies, etc. of the country/countries in which your company operates, including embargoes. See here a list of OFAC countries restrictions.

Restrict sales in specific countries based on credit cards

In addition to per-product selling restriction, 2Checkout also enables you to restrict sales to customers in specific markets based on the credit card they're using. This feature blocks an entire range of cards based on the first 6 digits of the credit card number (the Issuer Identification Number (IIN), or on the bank identification number (BIN)). This setting impacts your entire account, whereas per-product restrictions apply only to specific offerings.

2Checkout displays the following message to customers: "The payment could not be processed due to legal restrictions related to the country associated with this card. Please retry with a different card or choose to finalize the order with a different payment method."

You can contact 2Checkout directly if you require product sales to be restricted.

Restrict sales based on country

To restrict purchases from a certain country, you can use the settings in your Merchant Control Panel.

  1. Log in to your 2Checkout Control Panel.
  2. Go to Dashboard → Setup → Ordering options.
  3. Scroll down to the Billing countries section.
  4. Select a country from the left side column and move it to the restricted countries list on the right. This will prevent shoppers from selecting restricted countries for the billing address in the shopping cart.
  5. Click on the Save settings button at the bottom of the page to update your settings.

restrict countries.png

 

 

Retrieve a promotion

Overview

Use the getPromotion method to extract information on a promotion you set up for your account.

Parameters

Parameters Type/Description

sessionID

Required (string)

 

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

PromotionCode

Required (string)

 

System-generated identifier Avangate associated with promotion campaigns.

Response

Promotion object.

Request

<?php

require ('PATH_TO_AUTH');

$promotionCode = 'YOUR_COUPON_CODE';

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'getPromotion',
'params' => array($sessionID, $PromotionCode)
);
var_dump (callRPC((Object)$jsonRpcRequest, $host));

?>

PayPal Express Checkout

Overview

Use the PayPal Express checkout flow to minimize billing data entry for your shoppers, depending on the selected payment method, enabling you to further streamline the available single page checkout flows. This flow is particularly optimized to facilitate high volumes of payments via PayPal. 

 

Related links

Availability

PayPal Express Checkout is available for all account types on both business models (PSP & Reseller). 

Requirements

Use a currency parameter in the buy-link, preferably EUR or USD when pre-selecting PayPal as the payment method for the Express payments checkout, to ensure that the ordering process uses a PayPal supported currency.

If shoppers are geo-located in a market using a currency not supported by PayPal, the 2Checkout system automatically switches the currency to Euro (EUR), but only in scenarios in which PayPal is the pre-selected method for the Express payments checkout.

PayPal Express Checkout Flow 

The PayPal Express Checkout flow modifies the shopping cart design by positioning the payment methods selector area above the billing details section.

When using PayPal as the pre-selected payment method for the Express payments checkout flow, the cart displays a streamlined Billing Information area. Customers are only required to select the currency for the transaction that can be either EUR or USD.

express checkout_2.png

PayPal Express Checkout links query parameters

You can build buy-links for the PayPal Express Checkout flow manually. Use the parameters described below either with your custom domain or with https://secure.2checkout.com/order/checkout.php:

Parameter Description

NODATA = 1

Use in conjunction with PAY_TYPE=PAYPAL to trigger the Express payments checkout flow with PayPal which will circumvent 2Checkout checkout and redirect customers directly to PayPal. Expected behavior: Shoppers click on a Buy Link using the NODATA=1 andPAY_TYPE=PAYPAL parameters and are redirected to PayPal, rather than be taken to the 2Checkout shopping cart (checkout.php).

PAY_TYPE=PAYPAL

PayPal - preselected payment method for the order. It needs to be used in conjunction with the DESIGN_TYPE=1 parameter to trigger the Express payments checkout flow with PayPal.

CURRENCY (optional

Preselect the billing currency to be used in the transaction.

CLEAN_CART (optional)

Set this parameter to 1 to reset the cart contents or to ALL to reset the cart session. Use this parameter to remove products from the current cart session. Note: CLEAN_CART does remove production options or custom prices from the current cart session.

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.

  Value = 2. When DESIGN_TYPE=2 is used in Buy Links customers are redirected to their PayPal account, where they log in and confirm the payment. After payment confirmation, they are redirected to the shopping cart to confirm the billing and delivery data and enter their VAT ID.

Here's an example of such a link:

https://secure.2checkout.com/order/checkout.php?PRODS=1234567&QTY=1&COUPON=4066_100&CLEAN_CART=ALL

Generate an Express Payments Checkout buy-link for PayPal

  1. Navigate to Generate links under Setup.
  2. Select the Express payments checkout flow option in the list of purchase flows available under the Link options area.
  3. Select one or more products.
  4. Click on the Show advanced options link, and select PayPal from the Payment method drop-down menu in the Additional options area.
  5. Configure additional advanced options, if needed.
  6. Scroll down to the bottom of the page and click the Generate link button.
  7. The 2Checkout system will build a link such as the following:
https://secure.2checkout.com/order/checkout.php?PRODS=1234567&DESIGN_TYPE=1&PAY_TYPE=PAYPAL

Express Checkout Workflow with PayPal

  1. Shoppers click on the Express payments checkout flow with PayPal Buy-Link and are redirected to PayPal.
  2. Shoppers log in to PayPal and are displayed an order summary containing preliminary prices. Note: For free orders, 2Checkout needs to authorize $1/1EUR to validate the PayPal account (the credit/debit cards associated with the account). This is a common industry-wide practice for e-commerce companies. Pre-authorizations are designed to ensure that credit/debit cards and PayPal accounts (the credit/debit cards associated with PayPal accounts) are valid and that the necessary funds exist to charge customers for trial conversions and subscription renewals. Temporary charges used for the pre-authorization process are reversed within one hour.
  3. Shopper advances to the "Review your information" page. The Shipping address details from PayPal will be copied to the 2Checkout Billing and Delivery information.
  4. Shoppers click on Continue and are redirected back to the 2Checkout shopping cart in the verify.php page. Billing and Delivery information are not editable at this point. Depending on the shipping address in PayPal, the final costs of the order may vary, due to the addition of taxes.
  5. Shoppers click on Place Order to finish the purchase process.
  6. 2Checkout charges the shopper, which is taken to the Thank you page.

PayPal Express Checkout for ConvertPlus

  1. Navigate to Generate links under Setup.
  2. Select the ConvertPlus checkout flow option under the Checkout links area.
  3. Select one or more products.
  4. Configure additional options, if needed.
  5. Scroll down to the bottom of the page and click the Generate link button.
  6. The 2Checkout system will build a link such as the following:
https://secure.2checkout.com/checkout/buy?merchant=AVLRNG&tpl=default&prod=74B8E17CC0&qty=1

7. Copy and paste the link on your web store. When your shoppers click on the PayPal button in cart, to select it as a payment method, they will be redirected to PayPal, as shown in the image below.

paypalCVplusflow.png

FAQs:

1. Are free orders supported?

For free orders (with zero value) 2Checkout authorizes a minimum charge, for example, $1 when USD is the currency used for PayPal account validation purposes. 2Checkout subsequently returns the money to the shopper.

2. Can CARD=1 and CARD=2 parameters be used with the Express Payments Flow?

The Express payments flow supports both CARD=1 and CARD=2 parameters. 

Delete SKU by code

Overview

Use the deleteSkuByCode method to remove SKU information using the unique identifier you assign to the SKU schema. 

When requesting to delete SKU by code, the system will verify if the specific SKU is valid for that product code or pricing configuration code. If not, the 2Checkout system will return an error. The method supports multiple combinations of product code, pricing configuration code and SKU code in one call.

Request Parameters

Parameters Required Type/Description
ProductCode Required String. The product code that you can define for each of your offerings. Needs to be unique.
PricingConfigurationCode Optional String. Unique identifier of the pricing configuration.
SkuCode Optional String. Unique identifier of the SKU.

Request Example


Response Parameters

Parameters Type/Description
Product String. Unique identifier of the product.

Response Example


 

Enable/Disable products

Overview

Use the setProductStatus method to enable / disable products 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.
productCode Required (string)
 

Use this object to configure your subscription plan/products.

 

You can set all Product parameters except AvangateID. The 2Checkout system sets the unique product ID. The AvangateID is not editable.

Status Required (Boolean)
  True or False, depending on whether you want to enable or disable a subscription plan/product.
ReviewProductUrl Conditional (String)
  The URL where the product can be reviewed before approval. 
Parameter is required if the "Enabled" property is sent as TRUE and the product needs to be reviewed  by our internal teams before activation.
ReviewAdditionalDetails Optional (String)
  Additional information can be added to access the review of the product.

Request

<?php

require ('PATH_TO_AUTH');

$productCode = "YourProductCode";

$jsonRpcRequest = array (
'jsonrpc' => '2.0',
'id' => $i++,
'method' => 'setProductStatus',
'params' => array($sessionID, $productCode, true)
);

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

?>

 

Response

bool(true)

Contracts

Overview

Subscription contract period capabilities provide an increased level of control over the evolution and lifecycle of subscriptions sold to your customers, on top of billing cycles. Adding a contract period to a subscription means that you can configure subscriptions that:

  • Renew a number of times during a contractual period after which the contract is automatically restarted, unless customers opt-out;
  • Renew a number of times during a contractual period after which the contract expires causing the subscriptions it governs to be disabled and blocking customers from renewing, either automatically or through manual payments.

Availability

Contact 2Checkout directly if you wish to start using contracts for your subscriptions. 

Requirements

Subscription contract period functionality can be used only in conjunction with products for which subscriptions are generated.

Contract settings impact only active subscriptions.

Create a subscription contract period

To create a subscription contract period, follow the steps:

  1. Go to Setup -> Products.
  2. Ssearch and find the product for which you want to define a subscription contract
  3. Click Edit.
  4. Select the Billing cycle specific for the subscriptions generated for the product from the list of options available under the Billing cycle drop down menu. Note:Subscription contract period is not available when the one time fee option is selected / for evergreen subscriptions.
  5. Configure the Contract period in months.

Contract period options

There are two subscription contract periods:

  1. Unlimited - When this option is selected, Contracts have no impact on the billing cycle or the lifecycle of subscriptions. Essentially, subscription with the billing cycle set to 1 month will be renewed on a monthly basis indefinitely is the Contract option selected is unlimited.
  2. Limited to [number of months] - When this option is selected, the Contract limits billing cycles to the number of months you configure.

Use this option to define the period of time the subscription can be renewed, according to the billing cycles configuration, per contract agreed with your customers. In addition, you can also set the outcome of the Contract expiration, by choosing one of two options:

  1. Automatically renews - 2Checkout renews the Contract automatically at the end of the contract period defined with the same value (if it was not modified), unless customers choose to not prolong the agreement, by opting out of the contract. Contracts restart when subscriptions are renewed for the first time past the duration of the old contract. If the value of the Contract period is modified, it will only impact new subscriptions sold. Existing subscriptions move under the new Contract when they renewed for the first time past the period of the old contract.
  2. Expires - the Contract expires at the end of the contract period defined. When Contracts expire the subscriptions they govern also expire automatically, and will not be switched to the manual renewal model. Customers will not be given the chance to prolong their agreement and the life of the subscription. The 2Checkout system will not send out emails to let customers make payments manually to renew subscriptions and their Contracts.

Editing contract settings

Contract period settings for a product can be edited at any time. However, the new contract period set will only impact new subscriptions sold to customers. Existing subscriptions will continue to be governed by the same contract as when they were first sold, until the contract is automatically renewed or expires. When subscriptions are renewed, 2Checkout swapes the period parameters of the old contract for the current contract settings defined.

Subscription upgrades

For an upgrade from Product A to Product B, where both products have contract settings the expected behavior for the subscription is to switch start a new contract cycle according to Product's B settings.

 

Product A

Product B

Subscription after upgrade from Product A to Product B

Contract

Yes

Yes

Yes (Product B Contract period settings)

No

Yes

Yes

No

No (Product B Contract period settings)

No

No

Renew with new product version

  1. When renewing with a new product version, from Product A to Product B, where Product A has no contract settings and B has contract settings, the expected behavior for the subscription is to start a contract on Product B's Contract settings.
  2. When renewing with a new product version from Product A to Product B, where Product A nd Product B both have contract settings, the expected behavior for the subscription to have its contract period swapped to the Product B Contract settings the first time it's renewed past the Contract period of Product A.
  3. If the contract for Product A is set to expire, then subscriptions will work only until contract expiration deadline, after which they will be disabled, regardless if the contract settings of Product B, in the context of a renewal with a new product version.

Trials

Contracts for products for which you're offering free or paid trails to your customers only start impacting subscriptions after evaluation versions converted to paying products.

Shopper emails for contracts

In concert with Subscription contract period feature, you can control emails 2Checkout sends to customers. Two options are available to send shopper emails:

  1. For each Billing cycle period - Customers  continue to receive emails according to the setup in place and your strategy to communicate subscription renewals and charges. Messages include:
    • Renewal notifications
    • Order confirmations
    • Payment receipts
  2. At the end of the Subscription contract period - Emails are sent to customers only at the end of the subscription contract period. When this option is selected, the 2Checkout system blocks all emails from being sent to the customers using the subscriptions of the product impacted by this configuration. As such, customers will not receive:
    • Renewal notifications;
    • Order confirmations;
    • Payment receipts.

 

Send shopper emails each billing cycle period:

  • The 2Checkout system sends emails to shoppers each billing cycle for limited contracts that are set to automatically renew.
  • The 2Checkout system sends emails to shoppers each billing cycle except the last, after which subscriptions are disabled for limited contracts that are set to expire.

 

Send shopper emails each subscription contract period:

  • The 2Checkout system send emails to shoppers when they first purchase the subscription and at the end of the last billing cycle of the contract period as well as the first time they renew after the contract is restarted for limited contracts that are set to automatically renew.
  • The 2Checkout system send emails to shoppers only when they first purchase the subscription for limited contracts that are set to expire.

Manual renewal messages

Send shopper emails each:

  • Billing cycle period: shoppers continue to receive manual renewal notifications ahead of the next upcoming expiration deadline as long as they manually renew their subscription.
  • Subscription contract period: shoppers do not receive manual renewal notifications.

FAQ

  • What happens when the contract period is not a multiple of billing cycles?

    • If the contract period is not a multiple of billing period, for example a 7 months contract for a subscription set to renew every 3 months, then the 2Checkout system will allow subscriptions to be renewed either automatically or manually only as long as the contract period is not exceeded. For example, in the scenario of a 3 months billing cycle subscription governed by a 7 months contract there will be only 2 billing cycles/ contract, after which the contract auto-renews or expires, according to the settings you configured.

Pause subscription

Overview

Use the pauseSubscription method to suspend all automatic charges for a predefined time period for a subscription.

Request Parameters

Parameters Required Type/Description
SubscriptionRef Required String. The system-generated reference code of the subscription.
ResumeDate Required Number.  Date when the subscription should be resumed. Format "YYYY-MM-DD". The resume date needs to be set within 3 years starting from the day the subscription expires. The timezone used is the one on the server.
PauseReason Optional String. Freeform text filled in by the merchant. Text is limited to 100 characters.

Request Example

<?php
$sb = "58";
$vers = "6.0";
$client = new SoapClient("http://api.sandbox" . $sb . ".avangate.local/soap/$vers/?wsdl", array(
    'location' => "http://api.sandbox" . $sb . ".avangate.local/soap/$vers/",
    'cache_wsdl' => WSDL_CACHE_NONE,
    "trace" => 1));
$date = gmdate('Y-m-d H:i:s');
$merchantCode = "666999";
$key = "%y~8|m]T84p[W4+O1]_?";
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
$sessionID = $client->login($merchantCode, $date, $hash);
var_dump("session: ", $sessionID);
//$client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
$SubRef = "B7D8E72224";
$resumeDate = "2020-09-30 17:00:00";
$reason = "vacation leave";
try {
    $addPause = $client->setRenewalPause($sessionID, $SubRef, $resumeDate, $reason);
    var_dump("setRenewalPause:", $addPause);
} catch (SoapFault $e) {
    echo "Error setRenewalPause: " . $e->getMessage();
}
try {
    $renewalPause = $client->getRenewalPause($sessionID, $SubRef);
    var_dump("getRenewalPause:", $renewalPause);
} catch (SoapFault $e) {
    echo "Error getRenewalPause: " . $e->getMessage();
}
exit;

Response 

The pauseSubscription call returns the above TRUE/FALSE parameters.

Parameters Type/Description
SubscriptionRef

Boolean

  • TRUE - if the call was successful and a pause was scheduled; 
  • FALSE - if the pause mechanism is not enabled for the merchant OR any of the eligibility conditions were not met OR pause is not enabled for the product OR the maximum pause duration for the product was exceeded. In this case, the system also throws the following message: "The subscription is not eligible for pause."
ResumeDate

Boolean

  • TRUE - if the call was successful and a pause was scheduled; 
  • FALSE - if the pause mechanism is not enabled for the merchant OR any of the eligibility conditions were not met OR pause is not enabled for the product OR the maximum pause duration for the product was exceeded. In this case, the system also throws the following message: "The subscription is not eligible for pause."

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