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 currency.
Language	String	Required	The 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 scenario for price calculation. Must be one of does_not_affect, disable_existing.
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.Value	String	Optional	The price option value if the group is of type interval.
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 MONTHS, DAYS.
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.
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
SubscriptionReference	String	The subscription code.
DealPriceScenario	String	The provided DealPriceScenario.
DealSubscriptionScenario	String	The provided DealSubscriptionScenario.
DealDate	Datetime	The provided DealDate. Format: YYYY-MM-DD HH:MM:SS.
DealDueNowPriceNet	Float	The NET amount to be paid now.
DealDueNowPriceGross	Float	The GROSS amount to be paid now.
DealTaxAmount	Float	The tax amount.
DealTaxPercent	Int	The percent that the tax amount is covering from the GROSS price.
CurrentInfo	Object	The current subscription information.
CurrentInfo.ProductCode	String	The product code.
CurrentInfo.ProductName	String	The product name.
CurrentInfo.ProductDescription	String	The product description.
CurrentInfo.BillingPriceNet	Float	The NET price of a billing cycle.
CurrentInfo.BillingPriceGross	Float	The GROSS price of a billing cycle.
CurrentInfo.NoOfBillingCycles	Int	The number of billing cycles.
CurrentInfo.CurrentBillingCycle	Int	The current billing cycle number.
CurrentInfo.PayedBillingCycles	Int	The number of paid billing cycles.
CurrentInfo.RemainingBillingCycles	Int	The number of remaining billing cycles.
CurrentInfo.CurrentBillingCycleEndDate	Datetime	The end date of the current billing cycle. Format: YYYY-MM-DD HH:MM:SS.
CurrentInfo.TaxAmount	Float	The tax amount.
CurrentInfo.TaxPercent	Float	The percent that the tax amount is covering from the GROSS price.
CurrentInfo.BillingCyclesFrequency	String	The frequency of a billing cycle. Can of one of MONTHS, DAYS.
CurrentInfo.BillingCycleFrequencyUnit	String	The unit of a billing cycle.
CurrentInfo.ContractLength	Int	The contract length.
CurrentInfo.ContractLengthUnit	Int	The unit of the contract length. Ca be one of MONTHS, DAYS.
CurrentInfo.ProductOptions	Array	The array of existing product options.
CurrentInfo.ProductOptions.Code	String	The price option group code if the group is of interval type or the price option code otherwise.
CurrentInfo.ProductOptions.Value	String	The price option value if the group is of type interval.
NewDealInfo	Object	The new deal information.
NewDealInfo.ProductCode	String	The product code.
NewDealInfo.ProductName	String	The product name.
NewDealInfo.ProductDescription	String	The product description.
NewDealInfo.BillingPriceNet	Float	The NET price of a billing cycle.
NewDealInfo.BillingPriceGross	Float	The GROSS price of a billing cycle.
NewDealInfo.NoOfBillingCycles	Int	The number of billing cycles.
NewDealInfo.CurrentBillingCycle	Int	The current billing cycle number.
NewDealInfo.PayedBillingCycles	Int	The number of paid billing cycles.
NewDealInfo.RemainingBillingCycles	Int	The number of remaining billing cycles.
NewDealInfo.CurrentBillingCycleEndDate	Datetime	The end date of the current billing cycle. Format: YYYY-MM-DD HH:MM:SS.
NewDealInfo.TaxAmount	Float	The tax amount.
NewDealInfo.TaxPercent	Float	The percent that the tax amount is covering from the GROSS price.
NewDealInfoBillingCyclesFrequency	Int	The frequency of a billing cycle. Can of one of MONTHS, DAYS.
NewDealInfo.BillingCycleFrequencyUnit	String	The unit of a billing cycle.
NewDealInfo.ContractLength	Int	The contract length.
NewDealInfo.ContractLengthUnit	String	The unit of the contract length. Ca be one of MONTHS, DAYS.
NewDealInfo.ProductOptions	Array	The array of existing product options.
NewDealInfo.ProductOptions.Code	String	The price option group code if the group is of interval type or the price option code otherwise.
NewDealInfo.ProductOptions.Value	String	The price option value if the group is of type interval.
TotalsDealInfo	Object	General statistics regarding the subscription.
TotalsDealInfo.DealsNumber	Int	The total number of deals made so far.
TotalsDealInfo.ContractsNumber	Int	The total number of contracts made so far.
TotalsDealInfo.PaidBillingCycles	Int	The number of paid billing cycles.
TotalsDealInfo.ElapsedBillingCycles	Int	The number of elapsed billing cycles.

Error handling

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