Skip to main content

Add usage


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

$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);
    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 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 description Error code Error message
LICENCECODE is not a valid licence code for the merchant INPUT_ERROR 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 INPUT_ERROR Usage was not added as the option code provided is invalid.
Provided usage entries overlap within themselves or with existing usage entries INPUT_ERROR Usage was not added as the usage interval provided overlaps with an existing usage interval for the same LICENCECODE and OPTIONCODE combination.


Provided date formats are unsupported

INPUT_ERROR Usage start format unsupported. Please use YYYY-MM-DD HH:MM:SS.
Usage end format unsupported. Please use YYYY-MM-DD HH:MM:SS.



One or more mandatory parameters are missing or do not have the required format

INPUT_ERROR Usage was not added as one or more of the mandatory parameters are missing.
Usage was not added as one or more of the parameters do not match the required format.
Units not allowed.
Provided usages' start date is prior to the subscription start date or end date is after the subscription expiration date. INPUT_ERROR Usage interval out of bounds.
Unexpected error happens INTERNAL_ERROR <unexpected_error>