Skip to main content

Retrieve subscription deal information

Retrieve subscription deal information

Last updated: 27-Sep-2021
Rate this article:

Overview

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 name

Type

Required/Optional

Description

Currency

String

Required

The desired output currency.

Language

String Required

The desired output language.

Items

Array

Required

Each item corresponds to a subscription.

Items.DealDate

Datetime

Required

The date when the deal is set to come into effect. Format: YYYY-MM-DD HH:MM:SS.

Items.SubscriptionReference

String

Required

The subscription code.

Items.ProductCode

String

Required

The product code.

Items.Quantity

String

Required

The product quantity.

Items.DealPriceScenario

String

Required

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

String

Required

The scenarion for price calculation. Must be on of: start_new_deal_contract_now, start_new_deal_contract_after_current_cycle.

Items.PriceOptions

Array

Optional

The array of price options.

Items.PriceOptions.Code

String

Required

The price option group code if the group is of interval type or the price option code otherwise.

Items.PriceOptions.Options

Array

Optional

The array of options that belong to this option group.

Items.PriceOptions.Options.Value

String

Required

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

Object

Required

The product price.

Items.Price.Amount

Float

Required

The actual numeric amount.

Items.Price.Type

String

Required

Describes if the price type is catalog or custom. Can be only CUSTOM.

Items.Price.AmountType

String

Required

Describes if the price is NET or GROSS. Can be one of NET, GROSS.

Items.SubscriptionCustomSettings.CycleLength

Int

Required

The length of a single billing cycle.

Items.SubscriptionCustomSettings.CycleUnit

String

Required

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

Float

Required

The price of a single billing cycle.

Items.SubscriptionCustomSettings.CycleAmountType

String

Required

Describes the price type. Can be one of NET, GROSS.

Items.SubscriptionCustomSettings.ContractLength

Int

Required

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

Object

Required

The billing details.

BillingDetails.FirstName

String

Required

The first name.

BillingDetails.LastName

String

Required

The last name.

BillingDetails.CountryCode

String

Required

The country code. Must be one of the seller's associated country codes.

BillingDetails.State

String

Optional

Required only if the business model requires it.

BillingDetails.City

String

Required

The city name.

BillingDetails.Address1

String

Required

The address.

BillingDetails.Zip

String

Required

The zip code.

BillingDetails.Email

String

Required

The email address.

BillingDetails.Phone

String

Required

The phone number.

BillingDetails.Company

String

Required

The company's legal name.

BillingDetails.FiscalCode

String

Required

The fiscal code.

DeliveryDetails

Object

Required

The delivery details.

DeliveryDetails.FirstName

String

Required

The first name.

DeliveryDetails.LastName

String

Required

The last name.

DeliveryDetails.CountryCode

String

Required

The country code. Must be one of the seller's associated country codes.

DeliveryDetails.State

String

Optional

Required only if the business model requires it.

DeliveryDetails.City

String

Required

The city name.

DeliveryDetails.Address1

String

Required

The address.

DeliveryDetails.Zip

String

Required

The zip code.

DeliveryDetails.Email

String

Required

The email address.

DeliveryDetails.Phone

String

Required

The phone number.

DeliveryDetails.Company

String

Required

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": "o.mcmillan@integrawealth.net",
    "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": "m.frederick@integrawealth.net",
    "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 

Parameter name

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. Ca 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

<fiscal code validation error>

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

 

Rate this article:

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