Usage
Usage Overview
In the Nue API, Usage represents the consumption-based metrics that drive variable billing for services and products. Usage tracking enables businesses to implement pay-as-you-go models, tiered pricing structures, and hybrid subscription approaches that combine fixed and variable components.
What Is Usage-Based Billing?
Usage-based billing is a pricing model where customers are charged based on their actual consumption of services or resources rather than a fixed recurring fee. This model:
- Aligns costs with value: Customers pay for what they actually use
- Enables flexible pricing: Supports various consumption-based pricing strategies
- Provides transparency: Gives customers visibility into their consumption patterns
- Scales with customer growth: Naturally increases revenue as customer usage grows
To get started with Nue Usage Accelerator, please refer to this article.
Ingest Usage via API
Ingest Raw Usage
Raw usage represents a raw usage record that results from a measurable consumption of a product or service. It is characterized by various fields, including created date, customer ID, quantity, and timestamp, among others. After the raw usage records are uploaded, Nue rates them into billable usage records.
You can automate the usage ingestion using the Ingest Raw Usage API.
POST https://api.nue.io/usage/raw-usageFor example, the following API ingest 2 more raw usage records of the VROOM Webinar to Nue:
NOTE
It is important to make sure that the raw usage uploaded is processed only once. This objective can be achieved by selecting a deterministic transactionId that ensures that each raw usage has the unique transactionId. Nue ensures that raw usage records having the same ID will be processed once and only once.
curl --location 'https://api.nue.io/usage/raw-usage' \
--header 'apiAccessKey: {{apiAccessKey}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
"transactionId": "SUB-001336-001",
"data": [
{
"transactionId": "SUB-001336-001",
"customerId": "0015f00001UpHpvAAF",
"subscriptionNumber": "SUB-001336",
"timestamp": "2023-04-24T09:00:06.000Z",
"quantity": 129,
"properties": {
"region": "EU-1",
"clusterId": "1"
}
},
{
"transactionId": "SUB-001336-002",
"customerId": "0015f00001UpHpvAAF",
"subscriptionNumber": "SUB-001336",
"timestamp": "2023-04-20T09:00:06.000Z",
"quantity": 398,
"properties": {
"properties": {
"region": "EU-2",
"clusterId": "2"
}
}
}
]
}
'The custom attributes within the Properties element can be used to organize usage records into groups. A single subscription may contain multiple usage record groups, each of which is rated independently.
Manage Custom Fields in Raw Usage
Developers can create and manage custom Text fields on the Raw Usage object directly through the Nue metadata API.
Key capabilities include Create Custom Text Fields and Delete Custom Fields.
- We only support creating the ‘Text’ type custom field for now, and will support other types in the future. Newly created fields will be queryable via GraphQL.
- Updating a field is currently not supported; users can delete and recreate a field with the same API name to modify it.
After creating a custom field on the Raw Usage object, users can include this field in their CSV files when uploading raw usage data, or using Ingest Raw Usage API, populating it with their desired values.
Please refer to the API documentation for more information about the Nue Metadata API.
The following is an example:
POST /api/metadata/objects/RawUsage/fields:text
Content-Type: application/json
{
"apiName": "externalId",
"name": "External ID",
"minLength": 5,
"maxLength": 255
}Rated Usage
Optionally, you can ingest pre-rated usage using Ingest Rated Usage API. Unlike raw usage, rated usage can be submitted in multiple currencies. At billing time, usage records are grouped by currency and converted into invoice items.
POST https://api.nue.io/usage/rated-usage