Skip to main content

Save prices

Overview

Use the SOAP API 4 savePrices method to update product prices for a specific pricing configuration.

Parameters

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.

Prices

Array of BasicPrice objects

 

Details below.

Quantities

QuantityInterval object

 

Details below.

PriceOptions

Array of PriceOptionsAssigned objects

 

Details below. Required for FLAT (without base price) pricing configurations. Is NULL for DYNAMIC (with base price) pricing configurations.

PricingConfig

Required (PricingConfigurationIdentifier object)

 

System-generated unique pricing configuration code.

type

Require (string)

• REGULAR

• RENEWAL

 

BasicPrice

Object

Currency

String

 

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

Amount

Decimal

 

Basic price.

 

QuantityInterval

Object

MinQuantity

Int

 

The minimum quantity of volume discounts. Default is 1.

MaxQuantity

Int

 

The maximum quantity of volume discounts. Default is 99999.

 

PriceOptionsAssigned

Object

Code

String

 

Price option identifier.

Options

String

 

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

 

PricingConfigurationIdentifier

Object

ProductCode

String

 

The unique product code that you control.

Country

String

 

The country assigned to the pricing configuration you’re editing.

Response

bool(true)

Request

<?php

$host   = "https://api.2checkout.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 = "YOURCODE123"; //your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key          = "SECRET_KEY"; //your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.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;
}

$Prices                     = array();
$Prices[0]                  = new stdClass();
$Prices[0]->Currency        = 'USD';
$Prices[0]->Amount          = 999.99;
$Prices[1]                  = new stdClass();
$Prices[1]->Currency        = 'EUR';
$Prices[1]->Amount          = 111.99;
$Quantities                 = new stdClass();
$Quantities->MinQuantity    = 1;
$Quantities->MaxQuantity    = 99999;
$PriceOptions               = null;
//
$PriceOptions = array();
$PriceOptions[0] = new stdClass();
$PriceOptions[0]->Code = '04WCPNHWQ5';
$PriceOptions[0]->Options = array();
$PriceOptions[0]->Options[0] = 'loqmhwcpwk';
$PriceOptions[0]->Options[1] = 'n7332ux312';
$PriceOptions[1] = new stdClass();
$PriceOptions[1]->Code = '4CU1OVAGAA';
$PriceOptions[1]->Options = array();
$PriceOptions[1]->Options[0] = 'dvk7hv62jg';
$PriceOptions[1]->Options[1] = 'uf1svzaxcd';
//
$PricingConfig              = new stdClass();
$PricingConfig->ProductCode = 'NewSubscriptionPlan_Code_12345';
$PricingConfig->Country     = null;
$type                       = 'REGULAR';

try {
    $NewPrice = $client->savePrices($sessionID, $Prices, $Quantities, $PriceOptions, $PricingConfig, $type);
}

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

var_dump("NewPrice", $NewPrice);


?>

 

Retrieve recommended upsell campaign

Overview

Use the getRecommendedUpsellCampaign method via SOAP API 6.0 to find a campaign for the product code and the other sent filters.

Request Parameters

Parameter Name Type Required/Optional Description
SessionId String Required

Unique 2Checkout session ID code.

 

ProductCode String Required

The primary product code.

Quantity Integer Optional

The product quantity.

PriceOptions String Optional

The price options for the primary product.

EnabledForRenewals Boolean Optional

Returns only upsell campaigns that are enabled (or not) for renewals.

Request Example

<?php

require ('PATH_TO_AUTH');

$productCode = 'upsell_module_po';
$quantity = 13;
$priceOptions = 'option1,module_scale_po2=5';
$enabledForRenewals = true;

try {
    $results = $client->getRecommendedUpsellCampaign($sessionID, $productCode, $quantity, $priceOptions, $enabledForRenewals);
    var_dump($results);
}
catch (SoapFault $e) {
    var_dump($e->getMessage());
}

Response

Parameters Type Description

UpSell

Object

Object containing information related to the upsell campaigns, including product information and discount settings.

Create price option groups

Overview

Use the addPriceOptionGroup method to create price options for your subscription plans/products.

  • Send options for each pricing grouo or 2Checkout throws an exception.
  • When adding an interval with no min/max values or overlapping values, 2Checkout throws an exception. 

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.

PriceOptionsGroup

Required (object)

 

Use this object to create a new price option group for your account.

Response

bool(true)

Request

<?php

require ('PATH_TO_AUTH');

$PriceOptionGroup = new stdClass();
$PriceOptionGroup->Name = 'New Multi Users';
$PriceOptionGroup->Description = 'Quos aut ipsam ipsum omnis aut molestiae. Et quod molestias distinctio. Fugiat sit asperiores reprehenderit officia eaque quae quia. Aperiam quia quia illo eos nesciunt accusamus.';
$PriceOptionGroup->Translations = array();
$PriceOptionGroup->Translations[0] = new stdClass();
$PriceOptionGroup->Translations[0]->Name = 'xdrki7ljix';
$PriceOptionGroup->Translations[0]->Description = 'Beatae doloribus ipsam voluptatem et. Iure dignissimos non amet. Quibusdam fugiat dolor repudiandae temporibus harum.';
$PriceOptionGroup->Translations[0]->Language = 'en';
$PriceOptionGroup->Translations[1] = new stdClass();
$PriceOptionGroup->Translations[1]->Name = '37wr8ie2dj';
$PriceOptionGroup->Translations[1]->Description = 'Esse distinctio voluptatibus omnis et et quia dolor. Quibusdam dicta dolores odio consequatur velit voluptate. Laboriosam reiciendis libero vel quae molestiae ad.';
$PriceOptionGroup->Translations[1]->Language = 'ru';
$PriceOptionGroup->Type = 'RADIO';
$PriceOptionGroup->Options = array();
$PriceOptionGroup->Options[0] = new stdClass();
$PriceOptionGroup->Options[0]->Name = 'SingleUser';
$PriceOptionGroup->Options[0]->Description = 'Nisi ea autem a labore similique. Minus natus cumque nemo. Aut aliquam laboriosam dolorem ad.';
$PriceOptionGroup->Options[0]->Translations = array();
$PriceOptionGroup->Options[0]->Translations[0] = new stdClass();
$PriceOptionGroup->Options[0]->Translations[0]->Name = '0q2r3kcj0q';
$PriceOptionGroup->Options[0]->Translations[0]->Description = 'Voluptatem in vitae rerum ea tempore. Non cumque ullam optio quis. Laborum maxime sunt facere. Dolor fugit a fugiat quasi facere totam.';
$PriceOptionGroup->Options[0]->Translations[0]->Language = 'en';
$PriceOptionGroup->Options[0]->Translations[1] = new stdClass();
$PriceOptionGroup->Options[0]->Translations[1]->Name = 'dwfxuw4lrn';
$PriceOptionGroup->Options[0]->Translations[1]->Description = 'Debitis omnis maiores quia praesentium totam error corrupti. Consectetur eum magnam quam vero. Sit aperiam natus perspiciatis iusto sint ut fugit. Adipisci illum non voluptatem voluptas.';
$PriceOptionGroup->Options[0]->Translations[1]->Language = 'it';
$PriceOptionGroup->Options[0]->Code = 'singleuser1';
$PriceOptionGroup->Options[0]->SubscriptionImpact = new stdClass();
$PriceOptionGroup->Options[0]->SubscriptionImpact->Impact = 'Add';
$PriceOptionGroup->Options[0]->SubscriptionImpact->Months = 1;
$PriceOptionGroup->Options[0]->PriceImpact = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Method = 'FIXED';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts = array();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0] = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0]->Currency = 'USD';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[0]->Amount = 90.61;
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1] = new stdClass();
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1]->Currency = 'EUR';
$PriceOptionGroup->Options[0]->PriceImpact->Amounts[1]->Amount = 6.70;
$PriceOptionGroup->Options[0]->PriceImpact->ImpactOn = 'BASE';
$PriceOptionGroup->Options[0]->PriceImpact->Impact = 'ADD';
$PriceOptionGroup->Options[0]->PriceImpact->Percent = 39;
$PriceOptionGroup->Options[0]->Default = false;
$PriceOptionGroup->Options[1] = new stdClass();
$PriceOptionGroup->Options[1]->Name = 'MultiUser';
$PriceOptionGroup->Options[1]->Description = 'Vero voluptatum fuga et repellendus sed qui. Dolores molestiae error non ad aperiam. In error quos eum quas repudiandae pariatur et suscipit.';
$PriceOptionGroup->Options[1]->Translations = array();
$PriceOptionGroup->Options[1]->Translations[0] = new stdClass();
$PriceOptionGroup->Options[1]->Translations[0]->Name = 'MultiUser';
$PriceOptionGroup->Options[1]->Translations[0]->Description = 'Debitis et saepe facere blanditiis. Tempore et nemo aut ullam possimus ipsum nisi. Ad libero et consequuntur aliquam libero. Rerum aut illum eveniet earum.';
$PriceOptionGroup->Options[1]->Translations[0]->Language = 'en';
$PriceOptionGroup->Options[1]->Translations[1] = new stdClass();
$PriceOptionGroup->Options[1]->Translations[1]->Name = 'dw5zgkcki9';
$PriceOptionGroup->Options[1]->Translations[1]->Description = 'Vel et excepturi veniam. In iusto eveniet pariatur hic labore. Et qui dolorem accusantium molestias iusto.';
$PriceOptionGroup->Options[1]->Translations[1]->Language = 'pt';
$PriceOptionGroup->Options[1]->Code = 'multiuser999';
$PriceOptionGroup->Options[1]->SubscriptionImpact = new stdClass();
$PriceOptionGroup->Options[1]->SubscriptionImpact->Impact = 'ADD';
$PriceOptionGroup->Options[1]->SubscriptionImpact->Months = 2;
$PriceOptionGroup->Options[1]->PriceImpact = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Method = 'FIXED';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts = array();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0] = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0]->Currency = 'USD';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[0]->Amount = 65.03;
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1] = new stdClass();
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1]->Currency = 'EUR';
$PriceOptionGroup->Options[1]->PriceImpact->Amounts[1]->Amount = 64.58;
$PriceOptionGroup->Options[1]->PriceImpact->ImpactOn = 'BASE';
$PriceOptionGroup->Options[1]->PriceImpact->Impact = 'ADD';
$PriceOptionGroup->Options[1]->PriceImpact->Percent = 51;
$PriceOptionGroup->Options[1]->Default = true;
$PriceOptionGroup->Code = null;
$PriceOptionGroup->Required = false;

try {
    $NewPriceOptionGroup = $client->addPriceOptionGroup($sessionID, $PriceOptionGroup);
}

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

var_dump("NewPriceOptionGroup", $NewPriceOptionGroup);


?>

Pay-per-Usage

Use this option to create and assign PAYPERUSE price options to your portfolio.

For non PAYPERUSAGE cases, the Usage and UsagePricingModel fields are not required.

Request sample with PayperUse

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'addPriceOptionGroup';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Type": "INTERVAL",
    "Code": "PayPerUsage-CODE",
    "Required": false,
    "Name": "Pay per usage pricing option group",
    "Description": "Test option description",
    "Usage": "PAYPERUSAGE",
    "UsagePricingModel": "STEPPED",
    "Options": [
        {
            "Code": "9876545678",
            "ScaleMin": "1",
            "ScaleMax": "9",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        },
        {
            "Code": "98765456789",
            "ScaleMin": "10",
            "ScaleMax": "19",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        }
    ],
    "Translations": [
        {
            "Name": "Pay per usage pricing option group",
            "Description": "Test option description",
            "Language": "EN"
        }
    ]
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url.'?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Request sample without PayperUse

<?php
declare(strict_types=1);

class Configuration
{
    public const MERCHANT_CODE = '';
    public const MERCHANT_KEY = '';
    public const URL = 'http://api.2checkout.com/soap/6.0';
    public const ACTION = 'addPriceOptionGroup';
    public const ADDITIONAL_OPTIONS = null;
    //array or JSON
    public const PAYLOAD = <<<JSON
{
    "Type": "RADIO",
    "Code": "RADIO-CODE",
    "Required": false,
    "Name": "Radio pricing option group",
    "Description": "Test option description",
    "Options": [
        {
            "Code": "9876545678",
            "ScaleMin": "1",
            "ScaleMax": "9",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        },
        {
            "Code": "98765456789",
            "ScaleMin": "10",
            "ScaleMax": "19",
            "SubscriptionImpact": {
                "Months": "0.00",
                "Impact": null
            },
            "PriceImpact": {
                "Amounts": {
                    "USD": {
                        "Currency": "USD",
                        "Amount": "1.00"
                    },
                    "EUR": {
                        "Currency": "EUR",
                        "Amount": "6.00"
                    }
                },
                "ImpactOn": null,
                "Method": "FIXED",
                "Percent": null,
                "Impact": null
            },
            "Default": false,
            "Name": "translation_5f90150268bef",
            "Description": "Translation value",
            "Translations": [
                {
                    "Name": "translation_5f90150268bf7",
                    "Description": "Translation value",
                    "Language": "RO"
                },
                {
                    "Name": "translation_5f90150268bef",
                    "Description": "Translation value",
                    "Language": "EN"
                },
                {
                    "Name": "translation_5f90150268bf9",
                    "Description": "Translation value",
                    "Language": "FR"
                },
                {
                    "Name": "translation_5f90150268bf5",
                    "Description": "Translation value",
                    "Language": "RU"
                }
            ]
        }
    ],
    "Translations": [
        {
            "Name": "Radio pricing option group",
            "Description": "Test option description",
            "Language": "EN"
        }
    ]
}
JSON;
}

class Client
{
    public function call(
        string $url = Configuration::URL,
        $payload = Configuration::PAYLOAD,
        string $action = Configuration::ACTION
    ): ?object {
        if (is_array($payload)) {
            $payload = json_encode($payload);
        }
        if (!empty($payload)) {
            // SoapClient works with objects(StdClass)
            $payload = json_decode($payload);
        }
        $soapClient = $this->getClient($url);
        $sessionId = $this->getSession($soapClient);
        $args = array_filter([$sessionId, $payload]);

        return $soapClient->$action(...$args);
    }

    public function getClient(string $url): SoapClient
    {
        return new SoapClient(
            $url.'?wsdl',
            [
                'location' => $url,
                'cache_wsdl' => WSDL_CACHE_NONE,
            ]
        );
    }

    public function getSession(SoapClient $client)
    {
        $date = gmdate('Y-m-d H:i:s');
        $merchantCode = Configuration::MERCHANT_CODE;
        $key = Configuration::MERCHANT_KEY;
        $string = strlen($merchantCode).$merchantCode.strlen($date).$date;
        $hash = hash_hmac('md5', $string, $key);
        $client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');

        return $client->login($merchantCode, $date, $hash);
    }
}

try {
    $client = new Client();
    var_dump($client->call());
} catch (Exception $ex) {
    var_dump($ex);
}

Update a subscription

Overview

Change specific details about a subscription. Use the updateSubscription method to change specific details about a subscription.

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.
Subscription Required (Object)
  You need to include the entire Subscription object keeping its structure unchanged (retrieve it using getSubscription) but you can update only specific parameters enumerated below.
  EndUser Object
    End user details.
  ExpirationDate String
   

Subscription expiration date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ExpirationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00.

You cannot set an expiration date from the past.

  ActivationDate String
   

Subscription activation date - If you changed the time zone for the 2Checkout API by editing system settings under Account settings, then 2Checkout calculates the ActivationDate according to your custom configuration. Note: The default 2Checkout API time zone is GMT+02:00

This field is optional. If provided, it cannot be set lower than the subscription start date (creation/purchase date) and it can be changed only while the subscription is in pending activation

  SubscriptionEnabled Boolean
    Possible values: TRUE/FALSE
  RecurringEnabled Boolean
    Possible values: TRUE/FALSE
  ExternalCustomerReference String
   

Unique customer alphanumeric (string) identifiers that you control. Use this to 

move a subscription from under a customer to another customer entity. 2Checkout moves subscription under the customer for which you provide the External customer reference during the subscription update process. View example.

  ProductId Int
   

System-generated unique product ID. Needs to be the ID of an existing product in the 2Checkout system created under your account.

The product ID governs the product to which the subscription is associated with.

Product types must match Regular - Regular or Bundle - Bundle.

IDs must identify products with the renewal system enabled (max billing cycle 36 months).

  ProductName String
    The name of the product for identifier used under ProductID.
  ProductQuantity Int
    Ordered quantity.
  PriceOptionCodes Array
   

Array of product options codes. Pricing options codes are case sensitive.

To impact the renewal price, the PriceOptionsCodes need to belong to price options of pricing configurations used for the product with which the subscription is associated.

ChurnReasons Array
 

This payload can be sent only when the Subscription object (from above) will have RecurringEnabled set as TRUE. Possible values for this field are:
CHURN_REASON_NOT_SATISFIED_PRODUCT

CHURN_REASON_ENABLED_BY_MISTAKE

CHURN_REASON_PREFER_MANUAL

CHURN_REASON_ALREADY_RENEWED

CHURN_REASON_DONT_NEED

CHURN_REASON_WANT_PAUSE

CHURN_REASON_COVID

CHURN_REASON_HIGH_PRICE

CHURN_REASON_NOT_SATISFIED_SUPPORT

CHURN_REASON_EXTRAORDINARY

CHURN_REASON_OTHER

ChurnReasonOther String
  This field should have a value only if the ChurnReasons has the CHURN_REASON_EXTRAORDINARY or CHURN_REASON_OTHER values

 

All other parameters of the Subscription object are non-editable.

The 2Checkout system uses the updated subscription information for:

  • Manual and automatic renewals
  • Upgrades
  • Trial conversions

Response

Parameters Type/Description
Boolean true or false depending on whether the changes were successful or not.

Request

<?php

require ('PATH_TO_AUTH');

$subscriptionReferenceTest = 'YOUR_SUBSCRIPTION_REFERENCE';

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

$updatedSubscription = callRPC((Object)$jsonRpcRequest, $host, true);
var_dump ($updatedSubscription);
$updatedSubscription->RecurringEnabled = false;
$updatedSubscription->SubscriptionEnabled = true;
$updatedSubscription->ExpirationDate = '2020-12-12';

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

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

 

Retrieve subscriptions

Overview

Extract information on your account’s subscriptions.

Use the searchSubscriptions method to retrieve details about your account’s subscriptions, based on a set of filters. 

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.

SearchBy

Optional (Object)

 

Unique, system-generated subscription identifier.

 

SubscriptionSearchOptions parameters

Type/Description

CustomerEmail

Optional (string)

 

Customer email address. Can be NULL.

ExactMatchEmail Optional (Boolean)
  Force search by email to perform exact match; recommended to keep this option set to true in order to avoid matching similar email addresses from multiple customers.

DeliveredCode

Optional (string)

 

Activation key/code. Can be NULL.

AvangateCustomerReference

Optional (int)

 

System-generated customer reference. Can be NULL.

ExternalCustomerReference

Optional (string)

 

External customer reference that you control. Can be NULL.

Aggregate

Optional (boolean)

 

true - search will work across all your aggregated Avangate accounts.

false - default value. You limit the search to the account whose details you used for authentication.

Can be NULL.

SubscriptionEnabled

Optional (boolean)

 

true for enabled subscriptions.

false for disabled subscriptions.

Can be NULL.

RecurringEnabled

Optional (StringArray)

 

true – Avangate charges customers using recurring billing for subscriptions.

false – customers need to make manual payments to renew their subscriptions.

Can be NULL.

ProductCodes

Optional (StringArray)

 

Product identifier that you control. Can be NULL.

CountryCodes

Optional (string)

 

Country code (ISO 3166 two-letter code). Can be NULL.

PurchasedAfter

Optional (string)

 

YYYY-MM-DD. Subscription search interval start. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

PurchasedBefore

Optional (string)

 

YYYY-MM-DD. Subscription search interval end. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

ExpireAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions set to expire after a specific date. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

ExpireBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions set to expire before a specific date. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

RenewedAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions renewed after a specific date. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

RenewedBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions renewed before a specific date. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

NotificationAfter

Optional (string)

 

YYYY-MM-DD. Search subscriptions for which the Avangate system sent out notifications after a specific date. Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

NotificationBefore

Optional (string)

 

YYYY-MM-DD. Search subscriptions for which the Avangate system sent out notifications before a specific date Note: The default Avangate API time zone is GMT+02:00. Can be NULL.

Type

Optional (string)

 

trial - trial subscriptions.

regular - all generated subscriptions that are not trials.

regularfromtrial - subscriptions generated from a trial conversion.

Can be NULL.

TestSubscription

Optional (boolean)

 

true

false, depending on whether you want to include test subscriptions in the search or not. Can be NULL.

LifetimeSubscription

Optional (boolean)

 

true – evergreen subscriptions.

false - subscriptions with a limited recurring billing cycle, typically no larger than 36 months.

Can be NULL.

Page

Optional (int)

 

A specific page of search results. Default value is 1.

Can be NULL.

Limit

Optional (int)

 

Number of results (subscriptions) displayed per page. Default value is 10.

Can be NULL.

Response

Subscription

Array of objects

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;
}
$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail  = 'customer@email.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->AvangateCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default) 
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default) $SubscriptionSearch->Page = 1;$SubscriptionSearch->Limit = 25;
$SubscriptionSearch->Page = 1;
$SubscriptionSearch->Limit = 10;
try {
    $accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
    echo "accountSubscriptions: " . $e->getMessage();
    exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);

Remove promotion translations

Overview

Use the deletePromotionTranslations method to remove all localized texts from 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 add translations to.

Response

Parameters 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 translations from
$promotionCode = '';

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

 

Retrieve pricing configurations

Overview

Use the getPricingConfigurations method to extract information on the pricing configurations you set for a product.

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)

 

The editable code that you control at product-level, not the unique, system-generated product ID.

Response

Parameters Type/Description

PricingConfiguration

Array of objects

Request

<?php

require ('PATH_TO_AUTH');

$productCode = 'YOUR_PRODUCT_CODE';

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

?>

Enable a subscription

Overview

Use the enableSubscription method to enable a subscription.

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.

SubscriptionReference

Required (string)

 

Unique, system-generated subscription identifier.

Response

Boolean

true or false depending on whether the changes were successful or not.

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;
}
$SubscriptionReferenceTest = '0742B179DD';
try {
    $enabledSubscription = $client->enableSubscription($sessionID, $SubscriptionReferenceTest);
}
catch (SoapFault $e) {
    echo "enabledSubscription: " . $e->getMessage();
    exit;
}
var_dump("enabledSubscription", $enabledSubscription);

Add product coupon

Overview

Apply discount coupons to products added to the shopping cart.

Requirements

Parameters

Parameter Type/Description
sessionID Required (String)
  Session identifier, which is the output of the Login method. An exception is thrown if the values are incorrect.
coupon Required (String)
  The coupon/voucher code for a promotion impacting a product added to cart.

Response

Parameter Type/Description
Result Boolean
  True or false

Request

<?php

require('PATH_TO_AUTH'); // Authentication example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/02Authentication
require('PATH_TO_setPartner'); // setPartner example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/Partner/00Set_partner
require('PATH_TO_addProduct'); // addProduct example: https://knowledgecenter.avangate.com/Integration/Channel_Manager_API/SOAP/06Reference/08Place_an_order/00Add_product_to_cart

$couponCode = 'YOUR_CUPON_CODE';

try {
    $SetCoupon = $client->setCoupon ($sessionID, $couponCode);
} catch (SoapFault $e) {
    echo "Promotion: " . $e->getMessage();
    exit;
}
var_dump ("Promotion ", $SetCoupon);

Errors

Error Description

EMPTY_CART

The shopping cart is empty.

INVALID_COUPON_CODE

The coupon code is empty or invalid.

 

Search shipping methods

Overview

Use searchShippingMethods to retrieve information on the shipping methods currently defined on your account.

Search filters

Use the parameters below to filter the results of your search for shipping methods.

Parameter Type/Description
Name

String / Optional

Name of the shipping method.

Codes

Array of strings / Optional

Codes assigned to the shipping methods.

Countries

Array of strings / Optional

Countries to which the shipping method is assigned.

Active

Boolean / Optional

TRUE - active shipping methods

FALSE - inactive shipping methods

Pagination

Object / Optional

Control the results pagination.

  Page

Integer / Optional

Number of pages to display the results

  Limit

Integer / Optional

Limit the number of results of the search

Sample request

<?php

require ('PATH_TO_AUTH'); // authentication call

$SearchOptions = new \stdClass();
$SearchOptions->Name = 'ShippingMethodName'; // search for a specific shipping method
$SearchOptions->Codes = ['Code1', 'Code2', 'Code3']; // array of shipping method codes
$SearchOptions->Countries = ['US', 'UK', 'AU']; // array of country codes
$SearchOptions->Active = true; // only active shipping methods
$SearchOptions->Pagination = new \stdClass();
$SearchOptions->Pagination->Page = 1; // set display pages
$SearchOptions->Pagination->Limit = 200; // limit the results

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

Response

Parameter Type/Description
ShippingMethod

Object

 

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