Retrieve subscriptions
Overview
Extract information on your account’s subscriptions. Subscriptions can be retrieved starting with 5 minutes after their orders are generated in the 2Checkout system.
Use the searchSubscriptions method to retrieve details about your account’s subscriptions, based on a set of filters.
Parameters
|
Parameters |
Type/Description |
|
sessionID |
Required (string) |
|
|
Session identifier, the output of the Login method. Include sessionID into all your requests. 2Checkout throws an exception if the values are incorrect. The sessionID expires in 10 minutes. |
|
SearchBy |
Optional (Object) |
| Contains any combination of the available additional search filters. |
|
SubscriptionSearchOptions parameters |
Type/Description |
|
CustomerEmail |
Optional (string) |
|
|
Customer email address. Can be NULL. Note: The CustomerEmail parameter must be paired always with another reference pointing to the correct customer, such as the 2CheckoutCustomerReference parameter or the ExternalCustomerReference parameter. Otherwise, the search call will return partial hits on the customer email address. |
| ExactMatchEmail | Optional (Boolean) |
| Force search by email to perform exact match; recommended to keep this option set to true in order to avoid matching similar email addresses from multiple customers. | |
|
DeliveredCode |
Optional (string) |
|
Activation key/code. Can be NULL. |
|
|
2CheckoutCustomerReference |
Optional (int) |
|
|
System-generated customer reference. Can be NULL. |
|
ExternalCustomerReference |
Optional (string) |
|
|
External customer reference that you control. Can be NULL. |
|
Aggregate |
Optional (boolean) |
|
|
true - search will work across all your aggregated 2Checkout accounts. false - default value. You limit the search to the account whose details you used for authentication. Can be NULL. |
|
SubscriptionEnabled |
Optional (boolean) |
|
|
true for enabled subscriptions. false for disabled subscriptions. Can be NULL. |
|
RecurringEnabled |
Optional (StringArray) |
|
|
true – 2Checkout charges customers using recurring billing for subscriptions. false – customers need to make manual payments to renew their subscriptions. Can be NULL. |
|
ProductCodes |
Optional (StringArray) |
|
|
Product identifier that you control. Can be NULL. |
|
CountryCodes |
Optional (string) |
|
|
Country code (ISO 3166 two-letter code). Can be NULL. |
|
PurchasedAfter |
Optional (string) |
|
|
YYYY-MM-DD. Subscription search interval start. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
PurchasedBefore |
Optional (string) |
|
|
YYYY-MM-DD. Subscription search interval end. You can search for subscriptions purchased between the dates you set using PurchasedAfter and PurchasedBefore. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
ExpireAfter |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions set to expire after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
ExpireBefore |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions set to expire before a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
RenewedAfter |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions renewed after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
RenewedBefore |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions renewed before a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
NotificationAfter |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications after a specific date. Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
NotificationBefore |
Optional (string) |
|
|
YYYY-MM-DD. Search subscriptions for which the 2Checkout system sent out notifications before a specific date Note: The default 2Checkout API time zone is GMT+02:00. Can be NULL. |
|
Type |
Optional (string) |
|
|
trial - trial subscriptions. regular - all generated subscriptions that are not trials. regularfromtrial - subscriptions generated from a trial conversion. Can be NULL. |
|
TestSubscription |
Optional (boolean) |
|
|
true false, depending on whether you want to include test subscriptions in the search or not. Can be NULL. |
|
LifetimeSubscription |
Optional (boolean) |
|
|
true – evergreen subscriptions. false - subscriptions with a limited recurring billing cycle, typically no larger than 36 months. Can be NULL. |
|
Page |
Optional (int) |
|
|
A specific page of search results. Default value is 1. Can be NULL. |
|
Limit |
Optional (int) |
|
|
Number of results (subscriptions) displayed per page. Default value is 10. Can be NULL. |
Response
|
Array of objects |
Request
<?php
$host = "https://api.2checkout.com";
$client = new SoapClient($host . "/soap/4.0/?wsdl", array(
'location' => $host . "/soap/4.0/",
"stream_context" => stream_context_create(array(
'ssl' => array(
'verify_peer' => false,
'verify_peer_name' => false
)
))
));
function hmac($key, $data)
{
$b = 64; // byte length for md5
if (strlen($key) > $b) {
$key = pack("H*", md5($key));
}
$key = str_pad($key, $b, chr(0x00));
$ipad = str_pad('', $b, chr(0x36));
$opad = str_pad('', $b, chr(0x5c));
$k_ipad = $key ^ $ipad;
$k_opad = $key ^ $opad;
return md5($k_opad . pack("H*", md5($k_ipad . $data)));
}
$merchantCode = "YOUR_MERCHANT_CODE";// your account's merchant code available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$key = "YOUR_SECRET_KEY";// your account's secret key available in the 'System settings' area of the cPanel: https://secure.2checkout.com/cpanel/account_settings.php
$now = gmdate('Y-m-d H:i:s'); //date_default_timezone_set('UTC')
$string = strlen($merchantCode) . $merchantCode . strlen($now) . $now;
$hash = hmac($key, $string);
try {
$sessionID = $client->login($merchantCode, $now, $hash);
}
catch (SoapFault $e) {
echo "Authentication: " . $e->getMessage();
exit;
}
$SubscriptionSearch = new stdClass();
$SubscriptionSearch->CustomerEmail = 'customer@email.com';
$SubscriptionSearch->DeliveredCode = null;
$SubscriptionSearch->2CheckoutCustomerReference = null;
$SubscriptionSearch->ExternalCustomerReference = null;
$SubscriptionSearch->Aggregate = false;
$SubscriptionSearch->SubscriptionEnabled = null; //true false null
$SubscriptionSearch->RecurringEnabled = null; // true - autorenewal, false - manual renewal, null = both(default)
$SubscriptionSearch->ProductCodes = null; //array('Product_Code1', 'Product_Code2');
$SubscriptionSearch->CountryCodes = null;//array ('au')
$SubscriptionSearch->PurchasedAfter = null;
$SubscriptionSearch->PurchasedBefore = null;
$SubscriptionSearch->ExpireAfter = null;
$SubscriptionSearch->ExpireBefore = null;
$SubscriptionSearch->LifetimeSubscription = null;
$SubscriptionSearch->Type = 'regular'; //'trial', 'regular', 'regularfromtrial'
$SubscriptionSearch->TestSubscription = null; // true, false, null = both(default) $SubscriptionSearch->Page = 1;$SubscriptionSearch->Limit = 25;
$SubscriptionSearch->Page = 1;
$SubscriptionSearch->Limit = 10;
try {
$accountSubscriptions = $client->searchSubscriptions($sessionID, $SubscriptionSearch);
}
catch (SoapFault $e) {
echo "accountSubscriptions: " . $e->getMessage();
exit;
}
var_dump("accountSubscriptions", $accountSubscriptions);
