Add usage

Overview

Use the addSubscriptionUsage method in SOAP API v6 to add multiple usages at the same time.

Request Parameters

Parameters	Type	Required	Description
merchantCode	String	Required	The system-generated merchant ID.
sessionID	String	Required	Unique 2Checkout session ID code.
SubscriptionReference	String	Required	Unique 2Checkout subscription reference code.
hash	String	Required	The MD5 hmac key for the request.
OptionCode	String	Required	Unique 2Checkout option code.
UsageStart	Datetime	Required	Date when the usage starts. Format "YYYY-MM-DD". The timezone used is the one on the server.
UsageEnd	Datetime	Required	Date when the usage ends. Format "YYYY-MM-DD". The timezone used is the one on the server.
Units	Number	Required	Number of usage units consumed by user.
Description	String	Optional	It can be used to store a short merchant comment of the usage being uploaded. This can be anything, from the source of usage (mobile, web, etc.), to why changes occurred, etc. Example: Subscription usage for September.

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 = "B7D8E72224";

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->OptionCode = "scale";
    $subscriptionUsageRequest->UsageStart = "2025-03-02 10:00:10";
    $subscriptionUsageRequest->UsageEnd = "2025-04-01 10:00:10";
    $subscriptionUsageRequest->Units = 404;
    $response = $client->addSubscriptionUsage(
        $sessionID,
        $SubscriptionReference,
        [$subscriptionUsageRequest]
    );
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}
 exit;

Response

The successful addSubscriptionUsage call via SOAP APIv6 returns the Usage object.

array(1) {
      [0] =>
      class stdClass#3 (9) {
        public $usageReference =>
        string(12) "120011112191"
        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(30)
        public $description =>
        string(0) ""
        public $renewalOrderReference =>
        string(0) ""
      }
    }

Error Handling

Error message description	Error code	Error message
LICENCECODE is not a valid licence code for the merchant	INPUT_ERROR	Usage was not added as the license code provided is invalid.
OPTIONCODE is invalid for the Merchant and Licence or is not a usage-based option code	INPUT_ERROR	Usage was not added as the option code provided is invalid.
Provided usage entries overlap within themselves or with existing usage entries	INPUT_ERROR	Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination.
Provided date formats are unsupported	INPUT_ERROR	Usage start format unsupported. Please use YYYY-MM-DD HH:MM:SS.
Provided date formats are unsupported	INPUT_ERROR	Usage end format unsupported. Please use YYYY-MM-DD HH:MM:SS.
One or more mandatory parameters are missing or do not have the required format	INPUT_ERROR	Usage was not added as one or more of the mandatory parameters are missing.
		Usage was not added as one or more of the parameters do not match the required format.
		Units not allowed.
Provided usages' start date is prior to the subscription start date or end date is after the subscription expiration date.	INPUT_ERROR	Usage interval out of bounds.
Unexpected error happens	INTERNAL_ERROR	<unexpected_error>