Retrieve subscription deal information

Use the GetDealInfo method to retrieve information about the existing deal on a given subscription as well as what the subscription will look like with the new proposed deal being applied to it.

Request parameters

Parameter	Type / Description
Currency	Required (string) The desired output currency.
Language	Required (string) The desired output language.
Items	Required (array) Each item corresponds to a subscription.
Items.DealDate	Required (datetime) The date when the deal is set to come into effect. Format: YYYY-MM-DD HH:MM:SS.
Items.SubscriptionReference	Required (string) The subscription code.
Items.ProductCode	Required (string) The product code.
Items.Quantity	Required (string) The product quantity.
Items.DealPriceScenario	Required (string) The upgrade scenario to be applied. Must be one of: using_last_order_price, using_last_product_price, price_total, product_price_difference.
Items.DealSubscriptionScenario	Required (string) The scenarion for price calculation. Must be on of: start_new_deal_contract_now, start_new_deal_contract_after_current_cycle.
Items.PriceOptions	Optional (array) The array of price options.
Items.PriceOptions.Code	Required (string) The price option group code if the group is of interval type or the price option code otherwise.
Items.PriceOptions.Options	Optional (array) The array of options that belong to this option group.
Items.PriceOptions.Options.Value	Required (string) If the group is of type “scale”, this is a value from the allowed interval, otherwise, this is the option code as defined in Merchant Control Panel under “Unique Code”.
Items.Price	Required (object) The product price.
Items.Price.Amount	Required (float) The actual numeric amount.
Items.Price.Type	Required (string) Describes if the price type is catalog or custom. Can be only CUSTOM.
Items.Price.AmountType	Required (string) Describes if the price is NET or GROSS. Can be one of NET, GROSS.
Items.SubscriptionCustomSettings.CycleLength	Required (int) The length of a single billing cycle.
Items.SubscriptionCustomSettings.CycleUnit	Required (string) The unit of a single billing cycle. Can be one of MONTH, DAY. To perform a getDeal call towards a One Time Fee subscription, this value must be -1.
Items.SubscriptionCustomSettings.CycleAmount	Required (float) The price of a single billing cycle.
Items.SubscriptionCustomSettings.CycleAmountType	Required (string) Describes the price type. Can be one of NET, GROSS.
Items.SubscriptionCustomSettings.ContractLength	Required (int) The number of billing cycles contained in a single contract. To perform a getDeal call towards a One Time Fee or a Lifetime subscription, this value must be NULL.
BillingDetails	Required (object) The billing details.
BillingDetails.FirstName	Required (string) The first name.
BillingDetails.LastName	Required (string) The last name.
BillingDetails.CountryCode	Required (string) The country code. Must be one of the seller's associated country codes.
BillingDetails.State	Optional (string) Required only if the business model requires it.
BillingDetails.City	Required (string) The city name.
BillingDetails.Address1	Required (string) The address.
BillingDetails.Zip	Required (string) The zip code.
BillingDetails.Email	Required (string) The email address.
BillingDetails.Phone	Required (string) The phone number.
BillingDetails.Company	Required (string) The company's legal name.
BillingDetails.FiscalCode	Required (string) The fiscal code.
DeliveryDetails	Required (object) The delivery details.
DeliveryDetails.FirstName	Required (string) The first name.
DeliveryDetails.LastName	Required (string) The last name.
DeliveryDetails.CountryCode	Required (string) The country code. Must be one of the seller's associated country codes.
DeliveryDetails.State	Optional (string) Required only if the business model requires it.
DeliveryDetails.City	Required (string) The city name.
DeliveryDetails.Address1	Required (string) The address.
DeliveryDetails.Zip	Required (string) The zip code.
DeliveryDetails.Email	Required (string) The email address.
DeliveryDetails.Phone	Required (string) The phone number.
DeliveryDetails.Company	Required (string) The company's legal name.

Request sample

<?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 = 'getDealInfo';
    //array or JSON
    public const PAYLOAD = <<<JSON
 {
  "Currency": "us",
  "Country": "us",
  "Language": "ro",
  "CustomerIp": "91.220.121.21",
  "Source": "salesforce_cpq",
  "Items": [\
    {\
      "DealDate": "2021-09-20 23:59:59",\
      "SubscriptionReference": "MY2DD1E8P0",\
      "ProductCode": "CD297BBCE9",\
      "Quantity": 10,\
      "DealPriceScenario": "using_last_order_price",\
      "DealSubscriptionScenario": "prolong",\
      "Price": {\
        "Amount": 10,\
        "Type": "CUSTOM",\
        "AmountType": "NET"\
      },\
      "SubscriptionCustomSettings": {\
        "CycleLength": 1,\
        "CycleUnit": "MONTHS",\
        "CycleAmount": 10,\
        "CycleAmountType": "NET",\
        "ContractLength": 12\
      }\
    }\
  ],
  "BillingDetails": {
    "FirstName": "Oscar",
    "LastName": "McMillan",
    "CountryCode": "ro",
    "State": "Ilsios",
    "City": "RE",
    "Address1": "4519 Kovar Road",
    "Zip": "645",
    "Email": "[email protected]",
    "Phone": "6172938133",
    "Company": "Integra Wealth",
    "FiscalCode": "2816464"
  },
  "DeliveryDetails": {
    "FirstName": "Maria",
    "LastName": "Frederick",
    "CountryCode": "ro",
    "State": "New York",
    "City": "Buffalo",
    "Address1": "2033 Nuzum Court",
    "Zip": "14216",
    "Email": "[email protected]",
    "Phone": "7165708136",
    "Company": "Integra Wealth"
  }
}
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);
}

Response parameters

Parameter	Type / Description
Currency	String The currency code of all the returned price values.
DealDueNowPriceNet	Float The NET amount that needs to be paid.
DealDueNowPriceGross	Float The GROSS amount that needs to be paid.
DealTaxAmount	Float The tax amount (DealDueNowPriceGross - DealDueNowPriceNet).
Items	Array The array of response items, one for each subscription.
Items.SubscriptionReference	String The subscription code.
Items.DealPriceScenario	String The provided DealPriceScenario.
Items.DealSubscriptionScenario	String The provided DealSubscriptionScenario.
Items.DealDate	Datetime The provided DealDate. Format: YYYY-MM-DD HH:MM:SS.
Items.DealDueNowPriceNet	Float The NET amount to be paid now.
Items.DealDueNowPriceGross	Float The GROSS amount to be paid now.
Items.DealTaxAmount	Float The tax amount.
Items.DealTaxPercent	Int The percent that the tax amount is covering from the GROSS price.
Items.CurrentInfo	Object The current subscription information.
Items.CurrentInfo.ProductCode	String The product code.
Items.CurrentInfo.ProductName	String The product name.
Items.CurrentInfo.ProductDescription	String The product description.
Items.CurrentInfo.BillingPriceNet	Float The NET price of a billing cycle.
Items.CurrentInfo.BillingPriceGross	Float The GROSS price of a billing cycle.
Items.CurrentInfo.NoOfBillingCycles	Int The number of billing cycles.
Items.CurrentInfo.CurrentBillingCycle	Int The current billing cycle number.
Items.CurrentInfo.PayedBillingCycles	Int The number of paid billing cycles.
Items.CurrentInfo.RemainingBillingCycles	Int The number of remaining billing cycles.
Items.CurrentInfo.CurrentBillingCycleEndDate	Datetime The end date of the current billing cycle. Format: YYYY-MM-DD HH:MM:SS.
Items.CurrentInfo.TaxAmount	Float The tax amount.
Items.CurrentInfo.TaxPercent	Float The percent that the tax amount is covering from the GROSS price.
Items.CurrentInfo.BillingCyclesFrequency	String The frequency of a billing cycle for the current subscription as it is now.
Items.CurrentInfo.BillingCycleFrequencyUnit	String The unit of a billing cycle for the current subscription as it is now. Can be one of MONTHS, DAYS.
Items.CurrentInfo.ContractLength	Int The contract length for the current subscription as it is now.
Items.CurrentInfo.ContractLengthUnit	Int The unit of the contract length for the current subscription as it is now. Can be one of MONTH, DAY.
Items.CurrentInfo.ProductOptions	Array The array of existing product options.
Items.CurrentInfo.ProductOptions.Code	String The option group code as defined in the Merchant Control Panel under “Unique Code”.
Items.CurrentInfo.ProductOptions.Value	String The price option value if the group is of type interval or the price option code as defined in the Merchant Control Panel under “Unique Code” otherwise.
Items.NewDealInfo	Object The new deal information.
Items.NewDealInfo.ProductCode	String The product code.
Items.NewDealInfo.ProductName	String The product name.
Items.NewDealInfo.ProductDescription	String The product description.
Items.NewDealInfo.BillingPriceNet	Float The NET price of a billing cycle.
Items.NewDealInfo.BillingPriceGross	Float The GROSS price of a billing cycle.
Items.NewDealInfo.NoOfBillingCycles	Int The number of billing cycles.
Items.NewDealInfo.CurrentBillingCycle	Int The current billing cycle number.
Items.NewDealInfo.PayedBillingCycles	Int The number of paid billing cycles.
Items.NewDealInfo.RemainingBillingCycles	Int The number of remaining billing cycles.
Items.NewDealInfo.CurrentBillingCycleEndDate	Datetime The end date of the current billing cycle. Format: YYYY-MM-DD HH:MM:SS.
Items.NewDealInfo.TaxAmount	Float The tax amount.
Items.NewDealInfo.TaxPercent	Float The percent that the tax amount is covering from the GROSS price.
Items.NewDealInfoBillingCyclesFrequency	Int The frequency of a billing cycle for this subscription following an eventual deal change with the provided Items.SubscriptionCustomSettings. In case of a One Time Fee subscription, this value will be -1.
Items.NewDealInfo.BillingCycleFrequencyUnit	String The unit of a billing cycle for this subscription following an eventual deal change with the provided Items.SubscriptionCustomSettings. Can be one of MONTH, DAY.
Items.NewDealInfo.ContractLength	Int The contract length for this subscription following an eventual deal change with the provided Items.SubscriptionCustomSettings. In case of a One Time Fee or Lifetime subscription, this value will be NULL.
Items.NewDealInfo.ContractLengthUnit	String The unit of the contract length for this subscription following an eventual deal change with the provided Items.SubscriptionCustomSettings. Can be one of MONTH, DAY.
Items.NewDealInfo.ProductOptions	Array The array of existing product options.
Items.NewDealInfo.ProductOptions.Code	String The option group code as it's defined in the Merchant Control Panel under “Unique Code”.
Items.NewDealInfo.ProductOptions.Value	String The price option value if the group is of type interval or the price option code as defined in the Merchant Control Panel under “Unique Code” otherwise.
Items.TotalsDealInfo	Object General statistics regarding the subscription.
Items.TotalsDealInfo.DealsNumber	Int The total number of deals made so far.
Items.TotalsDealInfo.ContractsNumber	Int The total number of contracts made so far.
Items.TotalsDealInfo.PaidBillingCycles	Int The number of paid billing cycles.
Items.TotalsDealInfo.ElapsedBillingCycles	Int The number of elapsed billing cycles.

Error handling

Situation	Error Code	Error Message
Mandatory parameter(s) not provided	MALFORMED_PARAMETER	Currency not provided, Items.SubscriptionReference not provided, Items.Price.Type not provided, ...
DealDate not provided in required format	MALFORMED_PARAMETER	Invalid format provided for Items.DealDate. Format must be Y-m-d H:i:s. Provided: 2021-0920 23:59:59.
DealDate is in the past	MALFORMED_PARAMETER	Deal date 2020-09-20 23:59:59 is in the past.
Subscription not found or not associated with seller	VALIDATION_SUBSCRIPTION_MISSING	Subscription 6D4F1S81EEB not found.
Subscription not active	VALIDATION_SUBSCRIPTION_INACTIVE	Subscription 6D4F181EEB not active.
Product not found or not associated with seller	VALIDATION_PRODUCT_MISSING	Product with code 6A4C23036C not found.
Product not active	VALIDATION_PRODUCT_INACTIVE	Product with code 6A4C23036C not active.
The subscription is not B2B due to no custom renewal settings being found on subscription	VALIDATION_SUBSCRIPTION_NOT_B2B	No custom renewal settings found for subscription 6D4F1S81EEB. This subscription may not be a B2B subscription.
Provided price option groups are not valid price options for provided product	VALIDATION_PRICE_OPTION_MISSING	Some of the provided price options not found!
Provided subscription upgrade scenario not among supported values	VALIDATION_DEAL_SUBSCRIPTION_SCENARIO	Invalid upgrade subscription scenario provided: 'WRONG_SCENARIO'. Must be one of start_new_deal_contract_now, start_new_deal_contract_after_current_cycle.
Provided subscription price scenario not among supported values	VALIDATION_DEAL_PRICE_SCENARIO	Invalid price scenario provided: 'WRONG_SCENARIO'. Must be one of: using_last_order_price, using_last_product_price, price_total, product_price_difference.
Provided subscription price scenario not among supported values	VALIDATION_FISCAL_CODE
Invalid billing email provided	VALIDATION_BILLING_DETAILS	Invalid billing email provided.
Provided billing country not among seller supported countries.	VALIDATION_BILLING_DETAILS	Provided billing country not among seller supported countries.
Business model tax calculation type requires that BillingDetails.State be provided.	VALIDATION_BILLING_DETAILS	Business model tax calculation type requires that BillingDetails.State be provided.
Invalid delivery email provided	VALIDATION_DELIVERY_DETAILS	Invalid delivery email provided.
Provided delivery country not among seller supported countries.	VALIDATION_DELIVERY_DETAILS	Provided delivery country not among seller supported countries.
Business model tax calculation type requires that DeliveryDetails.State be provided.	VALIDATION_DELIVERY_DETAILS	Business model tax calculation type requires that DeliveryDetails.State be provided.
Country '{$deliveryCountryCode}' provided in two different business model distributions.	VALIDATION_BUSINESS_MODEL	Country provided in two different business model distributions.
Invalid price type detected for the next renewal price	INTERNAL_ERROR	Internal error
Unexpected error	INTERNAL_ERROR	Internal error