Overview

Use the updateDisplayType method to change the upselling display type for your campaigns between the values "overlay" or "interstitial".  

Request parameters

Response

The updateDisplayType method will return the  UpsellingDisplayType value after update.

Request sample

<?php

        require ('PATH_TO_AUTH');

        $request    = new stdClass();
        $request->Name  = "Updated proposal name";

        $jsonRpcRequest = new stdClass();
        $jsonRpcRequest->jsonrpc = '2.0';
        $jsonRpcRequest->method = 'updateDisplayType';
        $jsonRpcRequest->params = array($sessionID, $request);
        $jsonRpcRequest->id = $i++;

        try {
          $result = callRPC($jsonRpcRequest, $host);
          echo "Proposal: </br>", 
          var_dump($result);
        }
        catch (SoapFault $e) {
          echo "Could not fetch proposal: " . $e->getMessage();
          exit;
        }

Overview

Your shoppers can request refunds for their orders from 2Checkout myAccount. The refund process is described below:

1. A shopper requests a refund from 2Checkout myAccount.
2. The refund status of the order switches to Pending.
3. You receive a refund request notification from 2Checkout containing the details of the request. The email includes a link to the order details page in your 2Checkout account. Click the link to go to the order details page.
4. Click the You can view the refund details or cancel the request link.
5. Grant a partial or a total refund in the refund window. Once you've configured the refund type, click the Grant refund button to refund the order. You also have the option of rejecting refunds, but be advised that this option might drive the customer to open a chargeback dispute.
6. The order refund status in myAccount changes to Granted.

Edit granted refund requests

You can modify the refunded amount for each refund request only before 2Checkout processes them. If, for example, you have granted a partial refund and you want to modify the refunded amount, you can edit the refund request and the 2Checkout system will process the last granted request for each order. You can also change a partial refund to a total refund.

Each time you modify a granted refund request, the 2Checkout system sends an email to the shopper informing him or her about the granted refunded amount.

What happens when you don't approve a refund request

If you neither approve nor reject a refund request from a shopper, the request remains in Pending status for a set period of time (10 days by default). Depending on your 2Checkout account's settings, this limitation can vary. After that time interval expires, 2Checkout automatically approves the request if you take no action over it. 2Checkout recommends that you address customer complaints as a priority.

Where can I see shopper refund requests?

To get a detailed report of the refund requests placed by your shoppers, follow the steps below:

1. Go to Orders & customers -> Refunds.
2. Go to eStore refunds and enter the filters that you want to apply to your refund requests.
3. Click Search.
4. You can see a report of the refund requests including information such as the order reference number, when the request was placed, who placed it and the request status. You can also export the report in CSV format by clicking the Export as CSV button.

IMPORTANT: The GRANTED and APPROVED statuses apply only to the refund request and they are not displayed on the order status page in Control Panel.

Overview

Use the getTimezone method to retrieve information on the time zone used by your account for the 2Checkout API.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

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

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

Overview

Customer (subscriber) accounts centralize billing, subscription, and transaction data from the 2Checkout system. A single customer (subscriber) can own and use one or multiple subscriptions.

Requirements

Customer accounts/IDs can be associated exclusively with subscriptions generated by the 2Checkout system for products configured using Control Panel. To define identifiers yourself, or to have IDs generated automatically, your customers need to use at least one subscription generated for a product with the renewal system enabled.

Subscription status can be active, past due (in the grace period), expired, or canceled. Customer accounts are not supported for products with the renewal system disabled (without any subscriptions).

Subscription renewals

Subscription renewals will automatically be associated with the same customer using the initial subscription. A new customer account will not be generated for this scenario since the existing subscriber IDs are used.

Subscription renewal with a new product version

When the subscription for an older product being deprecated is renewed with the subscription of a newer product, it will automatically be associated with the same customer using the initial subscription. A new customer account will not be generated for this scenario since the existing customer IDs are used.

Upgrades

When the subscription for an older product is upgraded with the subscription of a newer product, it will automatically be associated with the same customer using the initial subscription. A new customer account will not be generated for this scenario since the existing customer IDs are used.

What's next

The What's next area is designed to provide an overview of upcoming automatic actions that the 2Checkout system will perform for the subscriptions under a customer account. It's designed to offer:

• Next billing dates and amounts for subscriptions;
• Next renewal notification dates.

Customer insight

This area reveals the date when the customer account was created.

Total customer value represents the total amount paid by a specific customer (converted to your default payout currency) for all subscriptions purchased for you as long as the orders that served to acquire them (including refunds) were finalized. Only revenue from Finalized orders is taken into consideration.

Orders with the same email address generate independent customers unless you specify the customer in the buy link.

Orders that do not generate subscriptions are not included in any customer value.

The all-time discount represents the total value of discounts offered to a specific customer. Again, only revenue from Finalized orders is taken into consideration.

The Customer insight area also provides details on all the subscriptions purchased by a customer along with information on their evolution in terms of renewals and upgrades.

Currency

The currency featured in the Customer insight area is the same as the default settlement currency for your account. In scenarios in which a customer purchased products from you in another supported currency, its value is converted into the default settlement currency.

Network Cross-selling

The Customer ID used in the buy link is limited to the customers of the vendor which owns the shopping cart. Subscriptions from third-party 2Checkout vendors will not be associated with the same customer ID as that of the main vendor.

Similarly, if your products are sold through network cross-selling by third-party 2Checkout vendors, customer IDs will be generated automatically by the system and will not be the same as the one set by the main vendor.

Customer Account Status

1. Active - a Customer Account is created when the first subscription for a product purchased by a customer becomes active. As long as at least one subscription associated with a customer remains active the Customer Account will also feature the Active status.
2. Trial - the Trial status is displayed for those Customer Accounts associated with customers using an active trial subscription.
3. Inactive - displayed when all subscriptions of a Customer Account are expired or canceled, or both.

Edit Customer Details

Click Edit at the bottom of the Customer billing details area to update the information associated with a specific account.

Select the checkbox next to the Update all customer subscriptions end-user details with these details option to also update the customer billing and end-user (delivery) details for all subscriptions governed by the same customer account.

Customer Search

The dedicated Customer area of Control Panel offers advanced search functionality designed to enable you to find particular or multiple customers. The underlying search technology has been optimized to deliver high performance and efficiency under an intuitive and easy to use interface.

You can only search for customers that have at least one subscription attached. Customers that were created via API (that are not tied to a subscription) cannot be found via the Control Panel Customers search.

Searches can be performed for:

• 2Checkout customer IDs;
• External customer IDs;
• Customer name/company;
• Customer email address;
• Order reference;
• External reference / PO;
• 2Checkout Subscription Reference;
• Activation key;
• Partner invoice no.;
• SKU.

The search technology used supports partial queries for customer name/company; email address; 2Checkout Subscription Reference; partner invoice no.; SKY and activation key. However, when using 2Checkout customer IDs, external customer IDs, order reference, and external reference number the query term must match exactly the data searched.

You can filter results returned by the Customer search based on:

• Customer status;
• Geographic regions;
• Customer country (the same country as specified in the billing details);
• The product(s) purchased by customers;
• The date when the customer was created in the 2Checkout platform;
• The date when a product was upgraded;
• The dates when notifications were sent to customers;

Export customer data

Customer data can be exported using the built-in functionality available alongside the search capabilities of the Merchant Control Panel.

Both customer details and subscription data are included in the CSV (comma-separated values) files that you can export. Essentially, information on single or multiple subscriptions acquired by the same customer is included in the CSV file.

For example, the exported CSV for the customer in the example below will feature two lines, one for each subscription purchased.

Optionally, you can also include the renewal price for customer licenses.

Workflow

Follow the steps below to generate a customer export file.

1. Log in to the 2Checkout Control Panel.
2. Go to Orders & customers -> Customers.
3. Use the existing filters to search for the customer you want to export data for.
4. Click Export as CSV.
5. Choose whether or not to include the renewal price for customer licenses.
6. Click Export.

Export fields

The table below shows the fields included in customer exports.

Time zone support

Customer search supports time zone selection, enabling you to choose either the default 2Checkout time zone (GMT + 02:00) or a custom time zone that you control via Account settings / Edit system settings.

The time zone selected in the Customer search area controls the timestamps in which data on specific customer details pages is reported.

Maximum number of results

Customer search displays a maximum of 1,000 results.

When exporting, a maximum of 100,000 items can be included in a single CSV (comma separated values) file. If you'd like more results beyond the first 100,000 to be exported, simply modify date settings to export results in batches of 100,000.

Aggregate Customer Subscription

Use the subscription import functionality to aggregate multiple, disparate subscriptions under a single customer.

In scenarios in which different orders from the same shopper generate multiple Customer accounts, each with its own ExternalCustomerId, you have the option of moving all subscriptions under the same customer. This can happen when you don't provide the same ExternalCustomerId for orders placed by the same shopper, for example, and the 2Checkout system needs to generate the customer identifier automatically.

When using the import process to move subscriptions from under a customer account to another, the mandatory LicenseUniqueId field needs to be left empty if the subscription in question doesn't feature such an identifier. If you provide an identifier, the 2Checkout system will detect the item you're importing as a new subscription and add it to the targeted customer account, while leaving the subscription you intended to move, but which did not feature a LicenseUniqueId, under its existing customer account. When LicenseUniqueId is left empty, add a new field labeled LicenseCode to the CSV file, and enter the corresponding subscription reference identifier. The LicenseCode field can be added at the end of the mandatory fields, just after ExternalCustomerId for example. The presence of the LicenseCode field along with the subscription reference value will help the 2Checkout system identify the subscription you want to move from one customer account to another.

To aggregate subscriptions from multiple Customer accounts of the same shopper, you need to edit customer data saved in the 2Checkout system. When importing data for multiple subscriptions already in the 2Checkout system, specify the same ExternalCustomerId in the columns of the CSV file.

Imported subscriptions for which the ExternalCustomerId of an existing customer was provided will automatically be moved under the same account.

Subscription aggregation scenarios

Move a single subscription from Customer A to Customer B.

Customer A features multiple subscriptions. Customer B must have an External Customer ID.

• Create a CSV file and import Subscription A belonging to Customer A but specify the External Customer ID of Customer B in the document.
• The 2Checkout system moves Subscription A from Customer A to Customer B. Customer A continues to be available.

Move multiple subscriptions from Customer A to Customer B.

Customer B must have an External Customer ID.

• Create a CSV file and import Subscription A, Subscription A1, and Subscription A belonging to Customer A but specify the External Customer ID of Customer B for all imported items in the document.
• The 2Checkout system will move Subscription A from Customer A to Customer B. Customer A will continue to be available, as long as it still features at least one subscription.

Move all subscriptions from Customer A to Customer B.

Customer B must have an External Customer ID.

• Create a CSV file and import all subscriptions belonging to Customer A but specify the External Customer ID of Customer B for all imported items in the document.
• The 2Checkout system will move all subscriptions from Customer A to Customer B. Customer A will no longer be accessible since it features no subscription, however, the account will be preserved in the 2Checkout system. As long as you know the External Customer ID of Customer A you will still be able to allow shoppers to place orders using this identifier in the Buy Links or to move subscriptions from different accounts under that of Customer A.

FAQ

What happens to subscriptions generated by the 2Checkout system before the new Customer Account functionality was available?
Individual Customer Accounts, each with its own unique numerical ID, will be created automatically for all subscriptions generated by the 2Checkout system. This is also valid for subscriptions imported in the 2Checkout system prior to the moment when this functionality went live.

Can the 2Checkout Customer ID be changed/deleted?
No. The unique 2Checkout Customer ID is locked and cannot be deleted or modified in any way.

Overview

Use the deleteSubscriptionUsages method via JSON-RPC API 6.0 to delete usage entered for a specific subscription, price options group, and usage interval.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = 'B7D8E72224';
$UsageReference = 120010776516;
$jsonRpcRequest = array('jsonrpc' => '2.0', 'method' => 'deleteSubscriptionUsages', 'params' => array($sessionID, 'SubscriptionReference' => $SubscriptionReference, array("UsageReference" => $UsageReference, "OptionCode" => 'USG_MN', "IntervalStart" => "2018-04-14 13:00:10", "IntervalEnd" => "2020-09-16 13:00:10")), 'id' => $i++);
var_dump ("deleteSubscriptionUsages", callRPC((Object)$jsonRpcRequest, $host));

Response

The deleteSubscriptionUsages method via JSON-RPC APIv6 returns NULL when successful.

class stdClass#3 (3) {
  public $code =>
  int(0)
  public $message =>
  string(46) ""
  public $data =>
  NULL
}

Error handling

The deleteSubscriptionUsages via JSON-RPC APIv6 returns FALSE if:

Overview

Use the updateSubscriptionUsage method via JSON-RPC API 6.0 to update a specific usage easier, or to update one usage line at a time, without having to create a file to do so.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = 'B7D8E72224';
$UsageReference = 120010776516;
$jsonRpcRequest = array('jsonrpc' => '2.0', 'method' => 'updateSubscriptionUsage', 'params' => array($sessionID, 'SubscriptionReference' => $SubscriptionReference, $UsageReference, array("Units" => 111, "Description" => "Test units out of bounds.")), 'id' => $i++);
var_dump ("updateSubscriptionUsage", callRPC((Object)$jsonRpcRequest, $host));

Response 

The updateSubscriptionUsage method via JSON-RPC APIv6 returns the Usage object if successful.

{
      "jsonrpc": "2.0",
      "id": 268,
      "result": {
        "UsageReference": "120011112631",
        "SubscriptionReference": "67F3AD6A32",
        "OptionCode": "USG_MN",
        "UsageStart": "2020-07-06 12:00:00",
        "UsageEnd": "2020-07-07 12:00:00",
        "Units": 12,
        "Description": "[CR Refactoring] 111 units",
        "RenewalOrderReference": 0
      }
    }

Error Handling

If unsuccessful, the updateSubscriptionUsage method via JSON-RPC APIv6 will return the error below.

Overview

Use the UpSellSettings object to update the merchant's displayType via JSON-RPC API 6.0. The 2Checkout Public API supports upsell campaigns which means you can invite your customers to purchase upgrades or add-ons from your own product catalog.

Parameters

Overview

Use the deleteUpSellCampaign method via JSON-RPC API 6.0 to permanently delete an upsell campaign in any status (active, disabled, expired).

Request parameters

Request sample

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/rpc/6.0';
    public const ACTION = 'deleteUpsellCampaign';
    public const ADDITIONAL_OPTIONS = null;
    public const PAYLOAD = "72937a15-1ffd-43b9-90b2-210d03dcd754";
}

class Client
{
    private const LOGIN_METHOD = 'login';
    private $calls = 1;
    private $sessionId;


    private function generateAuth(): array
    {
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $date = gmdate('Y-m-d H:i:s');
        $string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
        $hash = hash_hmac('md5', $string, $key);

        return compact('merchantCode', 'date', 'hash');
    }


    public function login(string $url)
    {
        $payload = $this->generateAuth();
        $response = $this->call($url, array_values($payload), self::LOGIN_METHOD);
        $this->sessionId = $response['result'];
    }


    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?array {
        if (empty($this->sessionId) && $action !== self::LOGIN_METHOD) {
            $this->login($url);
        }

        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload, Configuration::ADDITIONAL_OPTIONS];
        }
        $payload = array_filter($payload);

        $request = json_encode([
            'jsonrpc' => '2.0',
            'method' => $action,
            'params' => $payload,
            'id' => $this->calls++,
        ]);
        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
        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', 'Cookie: XDEBUG_SESSION=PHPSTORM'));
        curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
        $response = curl_exec($curl);
        if(empty($response)) {
            die('Server unavailable');
        }
        echo $response . '</br>';
        return json_decode($response, true);;
    }
}
$client = new Client();
$result = $client->call();
var_dump($result);

Response

• 204 - 'No content' if SUCCESS
• 4xx if FAILED with distinct error messages

Error handling

Overview

Use the searchProducts method to extract information about the subscription plan/products you configured for your account.

Pagination

Use pagination to decrease the request loading time, while better handling the returning responses.

Pagination works on all the search methods existing on 2Checkout API 5.0. The default pagination behavior is to display page 1 with 10 results. The maximum number of items displayed on a single page is 200.

To use pagination, include the Pagination object inside the search method call, using the parameters below:

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$SearchOptions = new stdClass();
$SearchOptions->Name = '2Checkout Subscription'; //Product name
$SearchOptions->Types = array ('REGULAR', 'BUNDLE'); //product type (standalone), regular or bundle
$SearchOptions->Enabled = True;
//$SearchOptions->GroupName = '';
$SearchOptions->Limit = '10';
$SearchOptions->Page = '10';

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

?>