Retrieve subscription deal information

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

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 = '1234554321';
    public const MERCHANT_KEY = 'D+~=z5R+R4])4D5&p56%';
    public const URL = 'http://api.avangate.local/rpc/6.0';
    public const ACTION = 'getDealInfo';
    //array or JSON
    public const PAYLOAD = <<<JSON
{
  "Currency": "usd",
  "Country": "us",
  "Language": "ro",
  "CustomerIp": "91.220.121.21",
  "Source": "salesforce_cpq",
  "Items": [
    {
      "DealDate": "2021-09-20 23:59:59",
      "SubscriptionReference": "L10RV2QPFZ",
      "ProductCode": "3EGZDNNRQY",
      "Quantity": 10,
      "DealPriceScenario": "using_last_order_price",
      "DealSubscriptionScenario": "prolong1",
      "Price": {
        "Amount": 200,
        "Type": "CUSTOM",
        "AmountType": "NET"
      },
      "SubscriptionCustomSettings": {
        "CycleLength": 1,
        "CycleUnit": "MONTHS",
        "CycleAmount": 10,
        "CycleAmountType": "NET",
        "ContractLength": 12
      }
    }
  ],
  "BillingDetails": {
    "FirstName": "Oscar",
    "LastName": "McMillan",
    "CountryCode": "ro",
    "State": "Ilios",
    "City": "RE",
    "Address1": "4519 Kovar Road",
    "Zip": "645",
    "Email": "o.mcmillan@integrawealth.net",
    "Phone": "6172938133",
    "Company": "Integra Wealth",
    "FiscalCode": "98414321421"
  },
  "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
{
    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(is_string($payload)) {
            $payload = json_decode($payload, true);
        }
        if (!empty($this->sessionId)) {
            $payload = [$this->sessionId, $payload];
        }
        $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 parameters

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