Retrieve usage

Overview

Use the getSubscriptionUsages method SOAP APIv6 to filter and retrieve usages for a subscription.

Request Parameters

Parameters	Type	Required	Description
merchantCode	String	Required	String. The system-generated merchant ID.
hash	String	Required	String. The MD5 hmac key for the request.
sessionID	String	Required	String. The system-generated code of the session.
SubscriptionReference	String	Required	String. The system-generated reference code of the subscription.
Page	Number	Required	Number. Page to be retrieved.
Limit	Number	Required	Number. The number of results per page.
IntervalStart	Datetime	Required	Date. Filters all usages with UsageEnd >= IntervalStart. Format "YYYY-MM-DD". The timezone used is the one on the server.
IntervalEnd	Datetime	Required	Date. Filters all usages with UsageEnd <= IntervalEnd. Format "YYYY-MM-DD". The timezone used is the one on the server.
RenewalOrderReference	Number	Optional	Number. The reference code generated by the system when the subscription is renewed.
OptionCode	String	Optional	Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing.

Request Sample

<?php
$sb = "58";
$vers = "6.0";
$client = new SoapClient("http://api.sandbox" . $sb . ".avangate.local/soap/$vers/?wsdl", array(
    'location' => "http://api.sandbox" . $sb . ".avangate.local/soap/$vers/",
    'cache_wsdl' => WSDL_CACHE_NONE,
    "trace" => 1));
$date = gmdate('Y-m-d H:i:s');
$merchantCode = "666999";
$key = "%y~8|m]T84p[W4+O1]_?";
$string = strlen($merchantCode) . $merchantCode . strlen($date) . $date;
$hash = hash_hmac('md5', $string, $key);
$sessionID = $client->login($merchantCode, $date, $hash);
var_dump("session: ", $sessionID);
//$client->__setCookie('XDEBUG_SESSION', 'PHPSTORM');
$subscriptionReference = 'EF4B51535B';
$usageReference = 120010492176;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->SubscriptionReference = $subscriptionReference;
    $subscriptionUsageRequest->Page = 1;
    $subscriptionUsageRequest->Limit = 10;
    $subscriptionUsageRequest->IntervalStart = '2020-04-09 16:40:00';
    $subscriptionUsageRequest->IntervalEnd = '2020-04-12 15:40:00';
    $response = $client->getSubscriptionUsages($sessionID, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;

Response

The getUsages method via SOAP APIv6 returns the Usage object when successful.

class stdClass#3 (2) {
      public $Items =>
      array(1) {
        [0] =>
        array(8) {
          'UsageReference' =>
          string(12) "120011114371"
          'SubscriptionReference' =>
          string(10) "67F3AD6A32"
          'OptionCode' =>
          string(6) "USG_MN"
          'UsageStart' =>
          string(19) "2020-07-06 12:00:00"
          'UsageEnd' =>
          string(19) "2020-07-07 12:00:00"
          'Units' =>
          int(7)
          'Description' =>
          string(15) "Response sample"
          'RenewalOrderReference' =>
          int(0)
        }
      }
      public $Pagination =>
      class stdClass#4 (3) {
        public $Page =>
        int(1)
        public $Limit =>
        int(10)
        public $Count =>
        int(1)
      }
    }

Error Handling

The below errors are returned when the getUsages method via SOAP APIv6 is unsuccessful.

Error message description	Error code	Error message
The provided parameters lack the required type or format.	SEARCH_PAGE_INVALID	The Page parameter must be a positive integer higher than or equal to 1.
	SEARCH_LIMIT_INVALID	The Limit parameter must be a positive integer lower than 100.
	MANDATORY_FIELDS_MISSING	Both 'IntervalStart' and 'IntervalEnd' parameters must be provided.
	FILTER_INVALID	If provided, 'RenewalOrderReference' must be a positive integer.
	FILTER_INVALID	'IntervalStart' must be provided in the following format: YYYY-MM-DD HH:MM:SS.
	FILTER_INVALID	'IntervalStart' must be provided in the following format: YYYY-MM-DD HH:MM:SS.
	FILTER_INVALID	'IntervalEnd' must be provided in the following format: YYYY-MM-DD HH:MM:SS.
	FILTER_INVALID	'IntervalEnd' must be provided in the following format: YYYY-MM-DD HH:MM:SS.
	SEARCH_PAGE_INVALID	'The Page parameter must be a positive integer higher than or equal to 1.
	SUBSCRIPTION_NOT_FOUND	Subscription not found.
Unexpected error happens	INTERNAL_ERROR	<unexpected_error>