--- title: "Create Usage Record" source_url: https://docs.rapyd.net/en/create-usage-record.html lang: en --- # Create Usage Record Create a usage record or update an existing usage record where its unique identifier is composed of `timestamp` and `subscription_item`. > **Note:** > > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Usage Record Errors](https://docs.rapyd.net/en/usage-record-errors.md "Usage Record Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - subscription_item - ID of the subscription item. String starting with **subi_**. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - action - Determines `quantity` for the usage record. One of the following values: - **increment** - Adds the quantity to the cumulative `quantity` of the usage record. - **set** - Replaces the `quantity` of the usage record. increment > **Note:** > > `action` has no impact when a new usage record is created. It is used to update an existing usage record where its unique identifier is composed of `timestamp` and `subscription_item`. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - quantity - The number of units of the service that the customer is billed for. - - timestamp - The date and time that the change to the usage takes effect. Timestamp must be in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). ### Response Parameters - - id - ID of the Usage Record object. String starting with **subiur_**. - - quantity - The number of units of the service that the customer is billed for. - - subscription_item - The ID of the subscription item that the usage record belongs to. String starting with **subi_**. - - timestamp - The date and time that the change to the usage takes effect. [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string subscriptionItem = "subi_3682d7bce9339f7b7c9e4185c7d1486f"; var requestObj = new { quantity = 10, timestamp = 1560866720, action = "increment", metadata = new { merchant_defined = true } }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/subscription_items/{subscriptionItem}/usage_records", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = { quantity: 10, timestamp: '1560866720', action: 'increment', metadata: { merchant_defined: true } }; const result = await makeRequest( 'POST', '/v1/subscription_items/subi_3682d7bce9339f7b7c9e4185c7d1486f/usage_records', body ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); $body = [ "quantity" => "10", "timestamp" => "1560866720", "action" => "increment", "metadata" => array( "merchant_defined" => true ) ]; try { $object = make_request('post', '/v1/subscription_items/subi_3682d7bce9339f7b7c9e4185c7d1486f/usage_records', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request subscription_item = "subi_3682d7bce9339f7b7c9e4185c7d1486f" usage_record_body = { "quantity": "10", "timestamp": "1560866720", "action": "increment" } response = make_request(method='post', path=f'/v1/subscription_items/{subscription_item}/usage_records', body=usage_record_body) pprint(response) ``` - /v1/subscription_items/{subscription_item}/usage_records - Create Usage Record - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items/subi_3682d7bce9339f7b7c9e4185c7d1486f/usage_records' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "quantity": "10", "timestamp": "1763462787", "action" : "increment" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "87af382d-9c95-467f-9481-6df07c3d485a" }, "data": { "id": "subiur_75c68e7754f4a6b3694f434b283c8c39", "quantity": 10, "timestamp": "1763462787", "subscription_item": "subi_56de709f3fc6f32c5db71d6c03611841" } } ``` - Bad Request - Timestamp Outside Current Billing Period - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items/subi_3682d7bce9339f7b7c9e4185c7d1486f/usage_records' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "quantity": "10", "timestamp": "176814048", "action" : "increment" }' ``` - ```json { "status": { "error_code": "ERROR_USAGE_RECORD_TIMESTAMP_NOT_VALID", "status": "ERROR", "message": "The request tried to create a usage record for a subscription item, but the timestamp was not valid. The request was rejected. Corrective action: Provide a valid Unix timestamp for a time in the current billing period for the relevant subscription.", "response_code": "ERROR_CREATE_SUBSCRIPTION_ITEM_USAGE_RECORD", "operation_id": "18a2c11a-c7f8-4a52-8f2d-241c4d1be857" } } ``` - Bad Request - Action Not Valid - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/subscription_items/subi_3682d7bce9339f7b7c9e4185c7d1486f/usage_records' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "quantity": "10", "timestamp": "1763462787", "action" : "decrement" }' ``` - ```json { "status": { "error_code": "ERROR_USAGE_RECORD_ACTION_NOT_VALID", "status": "ERROR", "message": "The request tried to create a usage record, but the action was not recognized. The request was rejected. Corrective action: Define the 'action' body parameter as 'increment' or 'set'.", "response_code": "ERROR_CREATE_SUBSCRIPTION_ITEM_USAGE_RECORD", "operation_id": "fe4b5401-d318-4e68-9f74-824f1ed3535e" } } ```