Skip to main content

Delete usage


Use the deleteSubscriptionUsages method via JSON-RPC APIv6 to delete usage entered for a specific subscription, price options group, and usage interval.

Request Parameters

Parameters Type Required/Optional Description
merchantCode String Required The system-generated merchant ID.
sessionID String Required The system-generated code of the session.
hash String Required The MD5 hmac key for the request.
SubscriptionReference String Required Unique code that represents a subscription. Example: 83FE4FEF2.
UsageReference Integer Optional The system-generated reference code for the usage of the subscription.
OptionCode String Optional Unique 2Checkout option code. The pay-per-usage price options group for which the usage is uploaded. Example: metered pricing. 
IntervalStart Datetime Optional (mandatory if IntervalEnd is provided) Deletes all usages where UsageEnd >= IntervalStart. Format "YYYY-MM-DD". The timezone used is the one on the server.
IntervalEnd Datetime Optional (mandatory if IntervalStart is provided) Deletes all usages where UsageEnd <= IntervalEnd. Format "YYYY-MM-DD". The timezone used is the one on the server.
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';
$UsageReference = 120010776516;
$jsonRpcRequest = array('jsonrpc' => '2.0', 'method' => 'deleteSubscriptionUsages', 'params' => array($sessionID, 'SubscriptionReference' => $SubscriptionReference, array("UsageReference" => $UsageReference, "OptionCode" => 'USG_MN', "IntervalStart" => "2018-04-14 13:00:10", "IntervalEnd" => "2020-09-16 13:00:10")), 'id' => $i++);
var_dump ("deleteSubscriptionUsages", 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 deleteSubscriptionUsages method via JSON-RPC APIv6 returns NULL when successful.

class stdClass#3 (3) {
  public $code =>
  public $message =>
  string(46) "NOT_FOUND: Usage line described does not exist"
  public $data =>

Error handling

The deleteSubscriptionUsages via JSON-RPC APIv6 returns FALSE if:

Error message code Error message description
Usage line described does not exist Data does not match records in our database (the LICENCECODE, OPTIONCODE and USAGE TIMESTAMP combination does not exist).
Usage was not updated as one or more of the mandatory parameters are missing Empty mandatory parameters.
One or more parameters lack the required format Incorrect data format in any of the parameters.
Usage was not deleted as this usage was already billed Lines to be deleted were already billed.


  • Was this article helpful?