Retrieve subscription deal information
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. |