Integrate with Existing Usage Systems

For businesses that already have a usage metering system in place, integrating that system with Nue, while still generating invoice items using Nue's billing engine, results in a streamlined approach to managing usage data and billing operations. This article will guide you through how to ingest rated usage from your existing metering system into Nue, allowing for seamless billing and invoicing.

The Separation of Rating and Billing

Nue is designed with a clear separation between usage rating and billing processes. This flexibility allows businesses to maintain their existing usage metering system - such as Metronome - while benefiting from Nue’s robust billing capabilities. Rather than relying on Nue to rate raw usage data, companies can ingest usage data that has already been rated by their existing system. This means you can continue using the processes and systems you are familiar with while gaining the additional advantages of Nue’s billing engine.

How It Works

The diagram below demonstrates the usage processing flow when integrating an external usage metering and rating system, such as Metronome, with Nue. While Metronome is used as an example in this illustration, the process is applicable to any external usage metering and rating systems.

 

1. Define Price Tags: In the initial stage, you define the price tags for your products and services within Nue. This ensures that the correct tiered pricing structure is in place for your usage products when the rated usage is ingested.
2. Pre-Rate & Order Processing: While your existing usage metering system manages the rating of usage data in real-time or on a scheduled basis, Nue handles pre-rating and order processing. This ensures that your quotes and orders, particularly those involving committed usage amounts or credit burndown models, are accurately calculated according to the tiered pricing structure defined in step 1 and are correctly presented to your customers.
3. Ingesting Rated Usage: Once usage has been rated by your metering system (e.g., Metronome), the data is ingested into Nue via API, specifically through the /usage/rated-usage endpoint. This data can be ingested in real-time or on a scheduled basis, depending on your needs. Nue also provides a UI to upload the rated usage record.  Once the rated usage is ingested, Nue associates it with the pre-rated order products to prepare for subsequent billing processing.
4. Billing & Invoicing: After the rated usage data has been ingested, Nue’s billing engine takes over. It loads the rated usage and generates invoice items for the corresponding product lines. Whether your billing model is based on overage or credit burndown models, Nue ensures that the correct billing structure is applied. At the end of the billing period, invoices are generated with accuracy and efficiency.
5. Visualization & Display: With the rated usage data in the system, Nue also provides valuable trending and reporting capabilities. You can forecast future usage trends, display relevant data, and use these insights to make informed business decisions.

Ingest or Upload Rated Usage

Nue provides 2 ways to ingest or upload rated usage: through API or on UI.

Ingest Rated Usage through API

Users can ingest rated usage through the Upload Rated Usage API. This approach is recommended when there is a need to frequently ingest large volumes of rated usage.

Endpoint

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

 

Example

curl --location 'https://api.nue.io/usage/rated-usage' \
--header 'Content-Type: application/json' \
--header 'nue-api-key: {{nue-api-key}}' \
--data '{
  "transactionId": "USAGE-240823144251",  
  "data": [
    {
      "transactionId": "USAGE-240823144251-001",
      "customerId": "001Ru00000GuO3HIAV",
      "subscriptionNumber": "SUB-000030",
      "timestamp": "2024-07-31T09:00:06.000Z",
      "quantity": 129,
      "ratedAmount": 199,
      "properties": {
        "region": "EU-1",
        "clusterId": "1"
      }
    },
    {
      "transactionId": "USAGE-240823144251-002",
      "customerId": "001Ru00000GuO3HIAV",
      "subscriptionNumber": "SUB-000030",
      "timestamp": "2024-07-31T09:00:06.000Z",
      "quantity": 398,
      "ratedAmount": 299,
      "properties": {
        "region": "EU-1",
        "clusterId": "1"
      }
    }
  ]
}'

The transactionId uniquely identifies each usage record, ensuring that usage with the same transactionId cannot have different data. This makes the API idempotent - running the API multiple times with the same transactionId and identical content will not result in data duplication.

 

The following outlines the properties of the ingested rated usage:

PROPERTY	DESCRIPTION	REQUIRED
transactionId	The transactionId uniquely identifies each usage record, ensuring that usage with the same transactionId cannot have different data.	Yes
customerId	The unique ID of the customer.     For customers from Salesforce, the ID needs to be the 18-character Salesforce ID of the account.	The customer ID and customer name are both valid methods for identifying a customer. Typically, the customer ID is required. However, if users prefer not to search for the customer ID in Nue when ingesting rated usage from an external system, they can provide the customer name - provided the customer name is unique across all customers and can accurately identify the customer.
customerName	The customer name.     The customerName value is not required if customerId is provided. Users may also provide a customerName value alone, but only if the customer name is unique across all customers, allowing Nue to accurately locate the corresponding customer ID.
subscriptionId	The subscription ID.     For subscriptions from Salesforce, the ID needs to be the 18-character Salesforce ID of the subscription.	The subscription ID, subscription number, product SKU, and product name are all valid methods for identifying a subscription. Typically, the subscription number is required. However, if users prefer not to search for the subscription number in Nue when ingesting rated usage from an external system, they can provide the product SKU or even the product name—as long as there is only one subscription for that product under the same customer and the product name uniquely identifies the product.
subscriptionNumber	The subscription number.
productSKU	The product SKU.
productName	The product name.
timestamp	The timestamp when the usage is rated.
quantity	The quantity of the usage.
ratedAmount	The rated amount in the currency of the subscription.
properties	The additional properties associated with the usage.

Upload Rated Usage on UI

Alternatively, users can upload rated usage through the UI by following these steps:

 

• Log in to the Nue App.
• In the menu search box, type "Usage" and navigate to the Usage page.
• Click on the "Upload" action and select "Rated Usage."
• Just like uploading raw usage, you can download a template and create a CSV file containing the rated usage based on the template.
• Import the rated usage file.

 

Once the usage records are successfully uploaded, they will be marked as "Rated." These records will be processed by the billing engine to generate invoice items at the end of the billing period, as products and services under the "Overage Usage" revenue model are typically billed in arrears. You can cancel the rated usage as long as it has not reached the "Billed" status.

 

When rated usage is ingested via API or UI, the Source field will be populated with the value "ExternalUsage" to distinguish it from raw usage ingested and rated by Nue, which will be tagged with the value "RawUsage.".  An example is shown below.  

 

 

Postman API Collection

You can find the Usage Postman API Collection here. Click the 'Run in Postman' button to import the collection into your Postman workspace.