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> |