Skip to main content
knowledgecenter.2checkout.com

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.

 

  • Was this article helpful?