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