Skip to main content

Update usage


Use the updateSubscriptionUsage method via JSON-RPC APIv6 to update a specific usage easier, or to update one usage line at a time, without having to create a file to do so.

Request Parameters

Parameters Type Required/Optional 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 Unique code that represents a subscription. Example: 83FE4FEF2.
Units Number Required (Optional if Description provided) Number of units recorded. Example: 10.
Description String Required (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

$host = 'http://api.sandbox58.avangate.local/rpc/6.0/';
$merchantCode = "666999";
$key = "%y~8|m]T84p[W4+O1]_?";
$string = strlen($merchantCode) . $merchantCode . strlen(gmdate('Y-m-d H:i:s')) . gmdate('Y-m-d H:i:s');
$hash = hash_hmac('md5', $string, $key);
$i = 1; // counter for api calls
// call login
$jsonRpcRequest = new stdClass();
$jsonRpcRequest->jsonrpc = '2.0';
$jsonRpcRequest->method = 'login';
$jsonRpcRequest->params = array($merchantCode, gmdate('Y-m-d H:i:s'), $hash);
$jsonRpcRequest->id = $i++;
$sessionID = callRPC($jsonRpcRequest, $host);
var_dump("session id:" . $sessionID);
// call api methods below
$SubscriptionReference = 'B7D8E72224';
$UsageReference = 120010776516;
$jsonRpcRequest = array('jsonrpc' => '2.0', 'method' => 'updateSubscriptionUsage', 'params' => array($sessionID, 'SubscriptionReference' => $SubscriptionReference, $UsageReference, array("Units" => 111, "Description" => "Test units out of bounds.")), 'id' => $i++);
var_dump ("updateSubscriptionUsage", callRPC((Object)$jsonRpcRequest, $host));

function callRPC($Request, $hostUrl, $Debug = false) {
    $curl = curl_init($hostUrl);
    curl_setopt( $curl, CURLOPT_POST, 1);
    curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt( $curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Accept: application/json'));
    $RequestString = json_encode($Request);
    curl_setopt( $curl, CURLOPT_POSTFIELDS, $RequestString);
    if (stristr($hostUrl, 'sandboxdev') || stristr($hostUrl, 'git-sb')) {
        curl_setopt( $curl, CURLOPT_PROXY, 'localhost:3128');
        //  curl_setopt( $curl, CURLOPT_PROXY, 'proxy.avangate.local:8080');
        //  curl_setopt( $curl, CURLOPT_PROXYUSERPWD, 'andrei.avramica:pw'); // for authenticated proxies
    $ResponseString = curl_exec ($curl);
    if (!empty($ResponseString)) {
        $Response = json_decode ($ResponseString,false);
        if (isset($Response->error) && !is_null($Response->error)) {
            var_dump($Response->error) ;
            return null;
        return $Response->result;
    } else {
        return null;


The updateSubscriptionUsage method via JSON-RPC APIv6 returns the Usage object if successful.

      "jsonrpc": "2.0",
      "id": 268,
      "result": {
        "UsageReference": "120011112631",
        "SubscriptionReference": "67F3AD6A32",
        "OptionCode": "USG_MN",
        "UsageStart": "2020-07-06 12:00:00",
        "UsageEnd": "2020-07-07 12:00:00",
        "Units": 12,
        "Description": "[CR Refactoring] 111 units",
        "RenewalOrderReference": 0

Error Handling

If unsuccessful, the updateSubscriptionUsage method via JSON-RPC 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.
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.