Update usage
Last updated: 15-Mar-2021
Rate this article:
Overview
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 the error 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. |
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. |
Rate this article: