OpenMeter Metering Policy

Send usage metrics to OpenMeter for metering and billing. This policy allows you to track API usage by sending events to OpenMeter's API in CloudEvents format.

With this policy, you'll benefit from:

Usage-Based Billing: Implement precise metering for pay-as-you-go pricing models
Real-Time Analytics: Track API usage patterns and customer behavior as they happen
Customizable Event Tracking: Capture specific metrics that matter to your business
Customer Segmentation: Identify usage patterns across different customer segments
Flexible Integration: Works seamlessly with OpenMeter's CloudEvents-based API
Batch Processing: Efficiently sends events in batches to minimize performance impact

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

Code(json)
 
{
  "name": "my-openmeter-metering-inbound-policy",
  "policyType": "openmeter-metering-inbound",
  "handler": {
    "export": "OpenMeterMeteringInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "customerId": "customer-123",
      "customerIdPropertyPath": ".data.accountNumber",
      "data": {
        "method": "GET",
        "route": "/hello"
      },
      "eventType": "request",
      "meterValue": 1,
      "source": "api-gateway",
      "url": "https://api.openmeter.io/api/v1/events"
    }
  }
}

Policy Configuration

name <string> - The name of your policy instance. This is used as a reference in your routes.
policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be openmeter-metering-inbound.
handler.export <string> - The name of the exported type. Value should be OpenMeterMeteringInboundPolicy.
handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

url (required) <string> - The URL of the OpenMeter API endpoint.
apiKey <string> - The API key to use when sending metering calls to OpenMeter.
eventType <string> - The type of event to use when sending metering calls to OpenMeter (overridable in code).
meterValue <number> - The value to use when sending metering calls to OpenMeter (overridable in code).
customerIdPropertyPath <string> - The path to the property on request.user contains the customer ID. For example .data.accountNumber would read the request.user.data.accountNumber property.
customerId <string> - The default customerId (subject) for all metering calls - overridable in code and by customerIdPropertyPath.
source <string> - The source identifier for the event (e.g. service name).
data <object> - A dictionary of additional data to be sent to OpenMeter (extensible in code).
statusCodes (required) <undefined> - A list of successful status codes and ranges "200-299, 304" that should trigger a metering call to OpenMeter.

Using the Policy

How it works

The policy sends usage events to OpenMeter's API in CloudEvents format whenever a request matches the configured status codes. The events include customer identification, event type, and custom data that can be used for metering and billing.

Configuration

Code(json)
 
{
  "type": "openmeter-metering-inbound",
  "handler": "$import(@zuplo/runtime).OpenMeterMeteringInboundPolicy",
  "options": {
    "url": "https://api.openmeter.io/api/v1/events",
    "apiKey": "your-api-key",
    "eventType": "api-request",
    "source": "zuplo-api",
    "customerId": "default-customer-id",
    "statusCodes": "200-299",
    "data": {
      "service": "payment-api"
    }
  }
}

Options

url (required): The URL of the OpenMeter API endpoint.
apiKey (optional): The API key to use when sending metering calls to OpenMeter.
eventType (optional): The type of event to use when sending metering calls to OpenMeter.
meterValue (optional): The value to use when sending metering calls to OpenMeter.
customerIdPropertyPath (optional): The path to the property on request.user that contains the customer ID.
customerId (optional): The default customerId (subject) for all metering calls.
source (optional): The source identifier for the event (e.g., service name).
data (optional): A dictionary of additional data to be sent to OpenMeter.
statusCodes (required): A list of successful status codes that should trigger a metering call to OpenMeter.

Dynamic Configuration

You can dynamically set properties for each request using the OpenMeterMeteringPolicy.setRequestProperties method:

Code(typescript)
 
import { OpenMeterMeteringPolicy } from "@zuplo/runtime";

export default async function (request, context) {
  // Set custom properties for this request
  OpenMeterMeteringPolicy.setRequestProperties(context, {
    eventType: "custom-event",
    customerId: "customer-123",
    meterValue: 5,
    data: {
      method: request.method,
      path: request.url,
      custom: "value",
    },
  });

  return request;
}

Example

Code(json)
 
{
  "type": "openmeter-metering-inbound",
  "handler": "$import(@zuplo/runtime).OpenMeterMeteringInboundPolicy",
  "options": {
    "url": "https://api.openmeter.io/api/v1/events",
    "apiKey": "your-api-key",
    "eventType": "api-call",
    "source": "payment-service",
    "statusCodes": "200-299",
    "data": {
      "service": "payment-api",
      "tier": "premium"
    }
  }
}

This configuration will send an event to OpenMeter for each successful API request (status codes 200-299) with the specified event type, source, and custom data.