---
title: Usage
slug: usage
docTags: 
createdAt: 2026-02-13T04:24:46.730Z
---

# 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](https://docs.nue.io/usage-accelerator-overview). 

***

# 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](https://api-docs.nue.io/ingest-raw-usage) API.

```text
POST https://api.nue.io/usage/raw-usage
```

For example, the following API ingest 2 more raw usage records of the VROOM Webinar to Nue:

:::hint{type="info"}
**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.
:::

```text
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](https://api-docs.nue.io/get-all-objects).

Key capabilities include [Create Custom Text Fields](https://api-docs.nue.io/create-custom-field) and [Delete Custom Fields](https://api-docs.nue.io/delete-custom-field)&#xNAN;**. **

- 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](https://api-docs.nue.io/ingest-raw-usage) API, populating it with their desired values.

Please refer to the [API documentation](https://api-docs.nue.io/create-custom-field) for more information about the Nue Metadata API.

The following is an example: 

```curl
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](https://api-docs.nue.io/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. 

```text
POST https://api.nue.io/usage/rated-usage
```

##