Overview

Use the updateSubscriptionUsage method via SOAP API 6.0 to update a specific usage entry.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$subscriptionReference = '4A1D733696';
$usageReference = 120010776516;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->Units = 123;
    $subscriptionUsageRequest->Description = 'Units 123';
    $response = $client->updateSubscriptionUsage($sessionID, $subscriptionReference, $usageReference, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;

Response 

The updateSubscriptionUsage method via SOAP APIv6 returns the Usage object if successful.

class stdClass#3 (8) {
      public $UsageReference =>
      120011112631
      public $SubscriptionReference =>
      "67F3AD6A32"
      public $OptionCode =>
      "USG_MN"
      public $UsageStart =>
      "2020-07-06 12:00:00"
      public $UsageEnd =>
      "2020-07-07 12:00:00"
      public $Units =>
      69
      public $Description =>
      ""
      public $RenewalOrderReference =>
      0
    }

Error Handling

If unsuccessful, the updateSubscriptionUsage method via SOAP APIv6 will return the error below.

Overview

Use the deleteSubscriptionUsages method via SOAP API 6.0 to delete one or more usage entries based on the provided criteria.

Request Parameters

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$subscriptionReferencee = '4A1D733696';
$usageReference = 120010776516;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->UsageReference = $usageReference;
    $subscriptionUsageRequest->OptionCode = 'Units 123';
    $subscriptionUsageRequest->IntervalStart = '2020-04-09 16:40:00';
    $subscriptionUsageRequest->IntervalEnd = '2020-04-12 15:40:00';
    $response = $client->deleteSubscriptionUsages($sessionID, $subscriptionReference, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;

Response 

The deleteSubscriptionUsages method via SOAP APIv6 returns NULL when successful.

NULL

Error Handling

The deleteSubscriptionUsages via SOAP APIv6 returns FALSE if:

Overview

Use the updateSubscriptionEndUser method to update the details of a subscription’s end user. This method changes per-subscription end user data and not customer details.

Parameters

Response

Request

<?php
$host   = "https://api.avangate.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
    'location' => $host . "/soap/4.0/",
    "stream_context" => stream_context_create(array(
        'ssl' => array(
            'verify_peer' => false,
            'verify_peer_name' => false
        )
    ))
));

function hmac($key, $data)
{
    $b = 64; // byte length for md5
    if (strlen($key) > $b) {
        $key = pack("H*", md5($key));
    }
    
    $key    = str_pad($key, $b, chr(0x00));
    $ipad   = str_pad('', $b, chr(0x36));
    $opad   = str_pad('', $b, chr(0x5c));
    $k_ipad = $key ^ $ipad;
    $k_opad = $key ^ $opad;
    return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$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
$now          = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash   = hmac($key, $string);
try {
    $sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
    echo "Authentication: " . $e->getMessage();
    exit;
}
$subscriptionreference = '8F749B63E7';
$EndUser = new stdClass ();
$EndUser->Address1 = 'Address line 1';
$EndUser->Address2 = 'Address line 2';
$EndUser->City = 'LA';
$EndUser->Company = 'Company Name';
$EndUser->CountryCode = 'us';
$EndUser->Email = 'customerAPI@avangate.com';
$EndUser->FirstName = 'New Customer';
$EndUser->Language = 'en';
$EndUser->LastName = 'Avangate';
$EndUser->Phone = '1234567890';
$EndUser->State = 'California';
$EndUser->Zip = '90210';
$EndUser->Fax = null;
try {
    $newEndUser = $client->updateSubscriptionEndUser($sessionID, $subscriptionreference, $EndUser);
}
catch (SoapFault $e) {
    echo "newEndUser: " . $e->getMessage();
    exit;
}
var_dump("newEndUser", $newEndUser);

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');

try {
    $Timezone = $client->getTimezone($sessionID);
}
catch (SoapFault $e) {
    echo "Timezone: " . $e->getMessage();
    exit;
}
var_dump("Timezone", $Timezone);

Overview

This section contains the objects returned as API responses, based on your requests to retrieve information on orders, products, subscriptions, promotions, and others.

Overview

Use the updateCustomerInformation method to update the details of a customer entity from the 2Checkout system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXT_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal 2Checkout customer reference

try {
    $existingCustomer = $client->getCustomerInformation($sessionID, $customerReference, $externalCustomerReference);
}

catch (SoapFault $e) {
    echo "existingCustomer: " . $e->getMessage();
    exit;
}

$existingCustomer->Email = 'newemailaddress@email.com';
$UpdateEndUserSubscriptions = false; // Optional, but if true the changes made on customer info are pushed to all subscriptions from this customer.

try {
    $updatedCustomerInfo = $client->updateCustomerInformation($sessionID, $existingCustomer, $UpdateEndUserSubscriptions);
}
catch (SoapFault $e) {
    echo "updatedCustomerInfo: " . $e->getMessage();
    exit;
}
var_dump("updatedCustomerInfo", $updatedCustomerInfo);

?>

Overview

Enable your customers to order on-demand renewals for their subscriptions using custom Buy-Links on ConvertPlus ordering flow.

Recommended resources

Availability

ConvertPlus renewal flow is available only to 2Checkout merchants that have activated ConvertPlus in their accounts. Contact 2Checkout for activation.

Requirements

Custom on-demand renewals buy links can be generated manually, and they work for active and past-due subscriptions (excluding trials and non-recurring/lifetime subscriptions). They can also be set from the Subscription page in Control Panel (Orders and customers à Subscriptions à Edit subscription details à Renew subscription).

Subscriptions can be renewed automatically ahead of their expiry deadline with 90 to 3000 days. The default platform renewal option is 370 days. Contact 2Checkout directly if you wish to customize this limitation.

Scenarios covered

1. Renew Subscription A belonging to Product A (source product) keeping it under Product A (target product).
2. Renew Subscription A belonging to Product A (source product) and moving/upgrading the customer to Product B (target product).

Workflow

Use this feature to enable your customers to renew their active and past-due subscriptions on demand, bypassing the upcoming renewal operation scheduled in the 2Checkout system.

Custom on-demand subscription renewals are performed:

1. From the moment when the items were scheduled to renew/expire. For example, let's assume that Subscription A (a monthly subscription), scheduled to expire June 30th, 2019, is renewed through the use of an on-demand link with a period of 10 days on June 22nd. Subscription A's lifetime will be prolonged with 10 days starting with June 30th, and the renewal/expiry deadline moved to July 10th. Moving forward, Subscription A will be renewed a month after the July 10threnewal, per its monthly renewal cycle.
2. By overriding the subscription billing cycle settings. However, following the custom on-demand renewal, the subscription will be governed by the renewal settings and pricing configuration of the product it's associated with.

Create a custom renewal link

Use the following parameters to generate ConvertPlus renewal links.

Examples

Renew the subscription with the same product and a specific pricing option

For this example, let's assume that we need a custom on-demand renewal link for Subscription A (monthly subscription expiring on June 30th, 2019 with the reference 9E0BAD7B5C) associated with Product A with the code product_a.

Use the following parameters to generate the renewal link:

• merchant=2COTEST
• subscription=9E0BAD7B5C
• prod=product_a
• opt=group_name:option_value

The resulting renewal link is:

https://secure.2checkout.com/checkout/renew/?merchant=2COTEST&subscription=9E0BAD7B5C&prod=product_a&opt=group_name:option_value

Renew a subscription with a different product

For this example, let's assume that we need a custom on-demand renewal link for Subscription A (monthly subscription expiring on June 30th, 2019 with the reference 9E0BAD7B5C) associated with Product A with the code product_a. In the renewal process, the customer will also be upgraded from Product A to Product B (code product_b).

Use the following parameters to generate the renewal link:

• merchant=2COTEST
• subscription=9E0BAD7B5C
• prod=product_b

The resulting renewal link is:

https://secure.2checkout.com/checkout/renew/?merchant=2COTEST&subscription=9E0BAD7B5C&prod=product_b

Domain use

1. secure.2checkout.com domain - If your account is using the 2Checkout's secure.2checkout.com domain, then this is what you need to include in your custom on-demand renewal links served to your customers, namely https://secure.2checkout.com/renewal/?.
2. Custom domains such as store.YourDomain.com - If your account is using a custom domain such as store.YourDomain.com, then this is what you need to include in your custom on-demand renewal links served to your customers, namely https://store.YourDomain.com /renewal/?

Control the ordering experience 

You can control some aspects of the ordering experience for customers using early renewal links, by appending the following parameters to the buy link created.

Overview

Use the UpSellSettings object to update the merchant's displayType via SOAP 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 updateCustomerInformation method to update the details of a customer entity from the Avangate system.

Parameters

Response

Request

<?php

require ('PATH_TO_AUTH');

$customerReference = CUSTOMER_REFERENCE;
$externalCustomerReference = 'EXTERNAL_CUSTOMER_REFERENCE'; //Optional, but if you include it it needs to belong to the same customer as the internal Avangate customer reference

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

$existingCustomer = callRPC((Object)$jsonRpcRequest, $host, true);
$existingCustomer->Email = 'newemailaddress@email.com';
$UpdateEndUserSubscriptions = false; // Optional, but if true the changes made on customer info are pushed to all subscriptions from this customer.

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

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

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 the update.

Request sample

<?php 

          require ('PATH_TO_AUTH'); 

          $textObj = new stdClass(); 
          $textObj->UpsellingDisplayType = "interstitial"; 

          try { 

            $upSellSettingsResponse = $client->updateDisplayType($sessionID, $textObj); 

          } catch (SoapFault $e) { 

            echo  $e->getMessage(); 

          }