Retrieve usage

Use the getSubscriptionUsages method via JSON-RPC API 6.0 to search through subscription usages and retrieve all the usage information attached to a subscription.

Request parameters

Parameter	Type / Description
merchantCode	Required (string) The system-generated merchant ID.
hash	Required (string) The MD5 hmac key for the request.
sessionID	Required (string) The system-generated code of the session.
SubscriptionReference	Required (string) The system-generated reference code of the subscription.
Page	Required (number) The page to be returned.
Limit	Required (number) The number of results per page.
IntervalStart	Required (datetime) Filters all usages where UsageEnd >= IntervalStart. Format "YYYY-MM-DD". The timezone used is the one on the server.
IntervalEnd	Required (datetime) Filters all usages where UsageEnd <= IntervalEnd. Format "YYYY-MM-DD". The timezone used is the one on the server.
OptionCode	Optional (string) Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing.
RenewalOrderReference	Optional (number) The renewal order unique identifier.

Request Sample

<?php
require ('PATH_TO_AUTH'); // authentication call
$SubscriptionReference = 'B7D8E72224';
$jsonRpcRequest = array(
    'jsonrpc' => '2.0',
    'method'  => 'getSubscriptionUsages',
    'params'  =>
        array(
            $sessionID,
            [
                'SubscriptionReference' => $SubscriptionReference,
                "Page"                  => 1,
                "Limit"                 => 10,
                "IntervalStart"         => "2020-07-01 10:40:00",
                "IntervalEnd"           => "2020-08-01 10:40:00",
                "RenewalOrderReference" => "11749701"
            ]
        ),
    'id'      => $i++
);
var_dump ("getSubscriptionUsages", callRPC((Object)$jsonRpcRequest, $host));

Response

The getUsages method via JSON-RPC APIv6 returns the Usage object when successful.

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