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 Integer 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

If unsuccessful, the updateSubscriptionUsage method via JSON-RPC APIv6 will return the error below.

class stdClass#3 (3) {
  public $code =>
  public $message =>
  string(124) "NOTHING_HAPPENED: The usage has not been updated, nothing to change. The provided values are identical to the existing ones."
  public $data =>