Skip to main content
knowledgecenter.2checkout.com

Add usage

Overview

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

Request Parameters

Parameters Type Required Description
merchantCode String Required Your unique 2Checkout merchant code.
sessionId String Required Unique 2Checkout session ID code. 
hash String Required The MD5 hmac key for the request.
SubscriptionReference String Required Unique code that represents a subscription. Example: 83FE4FEF2.
OptionCode String Required Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing. 
UsageStart Datetime Required

The datetime when the usage started; can be the same as UsageEnd. Example: 2018-09-03 17:28:32.

UsageEnd Datetime Required The datetime when the usage ended and is recorded. Example: 2018-09-03 17:28:32.
Units Integer Required Number of units recorded. Example: 10.
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
$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';
$jsonRpcRequest = array (
    'jsonrpc' => '2.0',
    'method' => 'addSubscriptionUsage',
    'params' => array($sessionID, $SubscriptionReference, array(array("OptionCode" => "MeteredPricing", "UsageStart" => "2020-02-22 15:40:00", "UsageEnd" => "2020-03-22 15:40:00","Units" => 10))),
    'id' => $i++
);
var_dump ("addSubscriptionUsage", 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);
    curl_setopt( $curl, CURLOPT_COOKIE, "XDEBUG_SESSION=PHPSTORM");
    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;
    }
}
exit;

Response 

The successful addSubscriptionUsage call via JSON-RPC APIv6 returns the Usage object.

{
"jsonrpc": "2.0",
"id": 260,
"result": [
{
"UsageReference": "120011112631",
"SubscriptionReference": "67F3AD6A32",
"OptionCode": "USG_MN",
"UsageStart": "2020-07-06 12:00:00",
"UsageEnd": "2020-07-07 12:00:00",
"Units": 10,
"Description": "",
"RenewalOrderReference": 0
}
]
}

Error handling

Error message code Error message description
Empty mandatory parameters Usage was not added as one or more of the mandatory parameters are missing.
Incorrect data format in any of the parameters Usage was not added as one or more of the parameters do not match the required format

Data does not match records in our database:​​

 

                           LICENCECODE is not a valid licence code for the merchant 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 Usage was not added as the option code provided is invalid.
Overlapping data Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination.
                     Check for overlaps At least one more record exists for the same LICENCECODE and OPTIONCODE combination where existing.USAGE START <= api.USAGE TIMESTAMP AND existing.USAGE TIMESTAMP <= api.USAGE START.
{
      "jsonrpc": "2.0",
      "id": 2,
      "error": {
        "code": 0,
        "message": "INPUT_ERROR: Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination",
        "data": null
      }
    }