Rate Table Formulas

Rate table formulas enable flexible, value-driven pricing models by allowing producers to define token consumption using formulas that combine multiple usage metrics, business parameters, or customer-specific factors. This provides the flexibility to align rates with the unique value delivered by the software, create differentiated offerings for diverse customer segments, and adapt monetization strategies as business needs evolve. By tying consumption more closely to customer value and usage patterns, producers can drive monetization outcomes that better reflect how their software is consumed in the market.

Using rate table formulas, producers can define pricing dynamically using spreadsheet-style expressions. Instead of assigning a fixed token cost (rate) to a product item, producers can calculate charges using one or more variables supplied at runtime.

Rate table formulas support rate calculation scenarios such as:

• Surge rate adjustments based on changing conditions
• Geography-based rates that vary by region or market
• Time-based rates that differ by time of day, day of week, or season
• Demand-based rates that respond to usage levels or demand patterns
• Resource consumption rates based on metrics such as CPU, memory, storage, or bandwidth usage
• Custom business-specific rate models tailored to unique monetization requirements

The goal is to provide a familiar and intuitive rate mechanism using spreadsheet-style formulas that those in roles such as Product Manager or End Customer buyers already understand.

In a rate table, each item must specify either a rate or a formula, but not both. If a rate table uses a formula with variables, the variables must be defined in the access request.

Formulas in rate tables use the same syntax and calculation rules as formulas in Microsoft Excel.

For details, see Create a rate table in the API reference.

You will find examples for defining variables in the access request in the next section, Access Request Behavior When Using Formulas

The following examples illustrate how Dynamic Monetization processes access requests for different formula configurations. Before submitting an access request, ensure that it satisfies the requirements described in Access Request Prerequisites.

• Access Request Behavior for Single Variable Rates
• Access Request Behavior with Multi-Variable Rate Formulas
• Access Request Behavior When Tokens Must Be Consumed From More Than One Line Item

The following prequisites and validation rules apply:

• The access request must contain either:
  • count (for standard rates or single-variable count-based formulas), or
  • variables (for multi-variable formulas)
• count and variables cannot be provided together.
• The variables object must contain at least one variable value.
• The variables object can include a variable named count.

The following examples illustrate valid and invalid access request structures.

Use count for standard rates and single-variable count-based formulas.

{
  "requester": {
    "type": "user",
    "value": "LisaBarry"
  },
  "requestedItems": [
    {
      "item": "ultrasound-ai",
      "version": "1.0",
      "count": 10
    }
  ]
}

Use the variables object when the rate formula requires one or more input variables.

{
  "requester": {
    "type": "user",
    "value": "LisaBarry"
  },
  "requestedItems": [
    {
      "item": "ultrasound-ai",
      "version": "1.0",
      "variables": {                
        "cpucycles": 2,
        "cores": 5
      }
    }
  ]
}

The count value can be supplied as a variable within the variables object.

{
  "requester": {
    "type": "user",
    "value": "LisaBarry"
  },
  "requestedItems": [
    {
      "item": "ultrasound-ai",
      "version": "1.0",
      "variables": {                    
        "count": 10,                    
        "cpucycles": 2,
        "cores": 5
      }
    }
  ]
}

The access request must contain either count or variables. Providing both is not supported.

{
  "requester": {
    "type": "user",
    "value": "LisaBarry"
  },
  "requestedItems": [
    {
      "item": "ultrasound-ai",
      "version": "1.0", 
      "count": 10,                     
      "variables": {                   
        "cpucycles": 2
      }
    }
  ]
}

This request includes both count and variables. The request fails validation because only one of these fields can be supplied.

When a single variable is used in a formula, the token consumption is calculated using a formula with the count variable. When a request is evaluated against this single variable formula, the system uses the count value supplied in the access request and substitutes it into the formula to determine the token charge.

This section explains the behavior when a single variable rate is used by means of an example.

Select the relevant tab to see the example values for the rate table as a table or as a JSON payload.

Select the relevant tab to see the example values for the access request as a table or as a JSON payload.

To respond to the request, the system substitutes the supplied count value for the variable in the rate table and evaluates the formula.

Select the relevant tab to see the example values for the access response as a table or as a JSON payload.

The formula uses the count value supplied in the access request to determine the token charge. In this example, a count of 10 results in a charge of 50 tokens (10 × 5).

Single variable formulas are easy to construct, keep access requests simple, and can model some helpful rate constructs, without changing the access requests. This means that you can replace a static rate with a formula for token consumption without changing the client implementation—which could already be supplying a count value.

Multi-variable rate formulas allow token consumption to be calculated using formulas that reference one or more variables supplied in the access request.

When a rate formula is used, the access request must provide the required variable values so the system can evaluate the formula and determine the token charge.

The following sections explain how access requests are processed for multiple-variable formulas and provide examples.

Select the relevant tab to see the example values for the rate table in table format or as a JSON payload.

Select the relevant tab to see the example values for the access request in table format or as a JSON payload.

The system substitutes the supplied variable values into the formula.

Select the relevant tab to see the example values for the access response in table format or as a JSON payload.

Each variable in the formula is replaced with its corresponding input value from the access request. In this example, the resulting calculation (8 × 10 × 2) produces a token charge of 160.

Multi-variable rate formulas enable token consumption to be calculated dynamically using values supplied in the variables section of the access request. This approach allows producers to implement more advanced pricing models.

If a line item does not contain enough available tokens to satisfy an access request, the system continues consuming tokens from the next eligible line item. Because different line items can reference different rates or formulas, the system follows specific rules to ensure token consumption is calculated consistently.

The following sections explain how rates and formulas are applied when token consumption spans multiple line items.

Once a function-based rate is applied, it becomes the governing mechanism for setting rates for the entire request. If additional line items are required to satisfy the request, the formula result from the first line item will be applied in all subsequent line items. Formulas or rate configured on subsequent line items will be ignored.

The following examples show how rates and formulas are applied when tokens are consumed from more than one line item.

Consider the following scenario: A client sends an access request for an item, and multiple line items are available that could satisfy the request:

• Line Item 1 contains 30 available tokens and expires on May 1, 2027.
• Line Item 2 contains 600 available tokens and expires on December 30, 2027.
• Line Item 1 uses formula A.
• Line Item 2 uses formula B.

Based on line item prioritization rules (see "Priority of Line Items", above), the system selects line item 1 first. It evaluates formula A and determines that the request requires 50 tokens.

Line item 1 contains only 30 available tokens, which are consumed first. The remaining 20 tokens are then consumed from line item 2.

The system does not evaluate formula B from line item 2. Instead, the token requirement calculated from formula A continues to govern the request, and the remaining tokens are consumed from subsequent line items using formula A until the request is satisfied.

The following table shows how token consumption is distributed across the line items and which formula is used to calculate the token charge.

The previous example explained the governing formula principle using a simplified scenario. This example illustrates the same behavior using sample line items, rate tables, and an access request.

Example Line items

The following tabs show the line items from which tokens can be consumed.

{
  "activationId": "ACT03-Elastic",
  "state": "DEPLOYED",
  "quantity": 100,
  "start": 1785542400000,
  "end": 1817078400000,
  "used": 70,
  "attributes": {
    "elastic": true,
    "rateTableSeries": "FormulaSeries1",
    "overdraftLimit": 0,
    "overdraftType": "string"
  }
}

In this example, line item 1 expires before line item 2. According to the line item prioritization rules, line item 1 is therefore consumed first.

Example Rate Tables

The following tabs show the rate tables associated with line items 1 and 2 for the item ultrasound-ai.

{
  "effectiveFrom":1785076543000,
  "series": "FormulaSeries1",
  "version": "4.7",
  "items": [
    {
      "name": "ultrasound-ai",                        
      "version": "1.0",
      "formula": "((count * cpucycles)/2) * 5"
    }
  ]
}

Example Access Request

A client sends an access request for item ultrasound-ai.

{
  "requester": {
    "type": "user",
    "value": "LisaBarry"
  },
  "requestedItems":[
    {
      "item": "ultrasound-ai",            
      "version": "1.0",                  
      "variables":{                      
        "count" : 10,                      
        "cpucycles": 2
      }
    }  
  ]
}

Consuming Tokens from Line Items

1. Evaluate Formula A on Line Item 1

   Formula A is:

   ((count * cpucycles) / 2) * 5

   Using the values supplied in the access request:

   ((10 * 2) / 2) * 5 = 50

   The request therefore requires 50 tokens.

2. Consume Available Tokens from Line Item 1

   Line item 1 contains only 30 available tokens.

   These 30 tokens are consumed first.

3. Continue Consumption on Line Item 2

   The request still requires 20 additional tokens.

   The system consumes those 20 tokens from line item 2.

   Formula B is not evaluated. The token requirement calculated using formula A continues to govern the request.

When token consumption spans multiple line items, the system evaluates the governing formula only once. If additional line items are required, the calculated token requirement is carried forward and used for the remainder of the request. Formulas defined on subsequent line items are ignored.

When transactions are recorded in the Data Warehouse, additional fields are populated to capture the rate or formula used to calculate token consumption.

The following fields provide visibility into both traditional rate-based and formula-based charging models:

The following example shows the values recorded for a transaction that uses a formula-based rate.

Consider a rate table configured with:

"formula" : "MULTIPLY(2, POWER(quantity, 2))";

and an access request containing:

"variables": {"quantity": 2}

The resulting transaction record contains the following values:

These fields allow reporting systems to determine not only the number of tokens consumed, but also the formula and input values that were used to calculate the token charge.