Update usage
Last updated: 15-Mar-2021
Rate this article:
Overview
Use the updateSubscriptionUsage method via JSON-RPC API 6.0 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
<?php
require ('PATH_TO_AUTH'); // authentication call
$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));
Response
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. |
Rate this article: