Update usage

Use the updateSubscriptionUsage method via SOAP API 6.0 to update a specific usage entry.

Request parameters

Parameters	Type	Required	Description
merchantCode	String	Required	The system-generated merchant ID.
hash	String	Required	The MD5 hmac key for the request.
sessionID	String	Required	The system-generated code of the session.
UsageReference	String	Required	The system-generated reference code for the usage of the subscription.
SubscriptionReference	String	Required	The system-generated reference code for the subscription.
Units	Number	Optional (Optional if Description provided)	Number of units used.
Description	String	Optional (Optional if Units provided)	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
require ('PATH_TO_AUTH'); // authentication call
$subscriptionReference = '4A1D733696';
$usageReference = 120010776516;

try {
    $subscriptionUsageRequest = new stdClass();
    $subscriptionUsageRequest->Units = 123;
    $subscriptionUsageRequest->Description = 'Units 123';
    $response = $client->updateSubscriptionUsage($sessionID, $subscriptionReference, $usageReference, $subscriptionUsageRequest);
    var_dump($response);
} catch (SoapFault $ex) {
    $faultname = (isset($ex->faultname)) ? " $faultname" : '';
    echo "[$ex->faultcode]$faultname: $ex->faultstring" . PHP_EOL;
}

exit;

Response

The updateSubscriptionUsage method via SOAP APIv6 returns the Usage object if successful.

class stdClass#3 (8) {
      public $UsageReference =>
      120011112631
      public $SubscriptionReference =>
      "67F3AD6A32"
      public $OptionCode =>
      "USG_MN"
      public $UsageStart =>
      "2020-07-06 12:00:00"
      public $UsageEnd =>
      "2020-07-07 12:00:00"
      public $Units =>
      69
      public $Description =>
      ""
      public $RenewalOrderReference =>
      0
    }

Error Handling

If unsuccessful, the updateSubscriptionUsage method via SOAP APIv6 will return one of the errors below.

Error message description	Error code	Error message
Provided parameters lack the required type or format.	MALFORMED_PARAMETER	One or more parameters lack the required format: SubscriptionReference must be a string.
	MALFORMED_PARAMETER	One or more parameters lack the required format: UsageReference must be a positive integer higher than or equal to 1.
	PARAMETER_MISSING	Please provide at least one of the following parameters: Units, Description.
	MALFORMED_PARAMETER	One or more parameters lack the required format: Units must be a positive integer higher than or equal to 1.
	MALFORMED_PARAMETER	One or more parameters lack the required format: Description must be a string.
Subscription or usage line are not found.	NOT_FOUND	Subscription not found.
	NOT_FOUND	Usage line described does not exist.
Usage line is already billed.	ALREADY_BILLED	Usage was not updated as this usage was already billed.
The renewal process is in progress for this subscription.	RENEWAL_IN_PROGRESS	There is a renewal in progress for the provided usage line.
The usage was not changed after the update.	NOTHING_HAPPENED	The usage has not been updated, nothing to change. The provided values are identical to the existing ones.
An unexpected error happens.	GENERIC	There has been an error updating the usage line. Please try again later.