Get Started

#Prerequisites

You need to have an instance of OpenMeter running and configured. If you haven't yet, watch our Getting Started guide. We'll be using the Node.js OpenMeter SDK, but the concepts are the same whether using an SDK, the API, or the Cloud UI.

#1. Create your first feature

Features are the building blocks of your product offering, they represent the various capabilities of your system, and practically speaking they typically transalte to line items on your pricing page.

OpenMeter has metered and non-metered features. A feature is metered if you associate a meter to it at creation, then usage information about the feature can be tracked and queried through that meter. Features only support meters with SUM and COUNT aggregation types!

import { OpenMeter } from '@openmeter/sdk';
 
// Connect to locally running OpenMeter instance
const openmeter = new OpenMeter({
  baseUrl: 'http://127.0.0.1:8888',
});
 
// Create feature GPT-4 Tokens
const feature = await openmeter.features.create({
  key: 'gpt_4_tokens',
  name: 'GTP-4 Tokens',
  meterSlug: 'tokens_total',
  meterGroupByFilters: {
    model: 'gpt-4',
  },
});

In the above snippet we use the tokens_total meter from our config.example.yaml to create a feature for GPT-4 Tokens. That meter has a groupBy defined for the model being used, and here at feature creation we can filter on that groupBy to only include gpt-4 usage.

#2. Giving access to a customer

You can give access to your features by creating entitlements. Entitlements define under what conditions a subject can access a feature. In this example, we'll create a metered entitlement that enables you to define usage based access to a feature. It works by running a balance calculation for the current usage period: you grant usage allowances to a subject, and OpenMeter deducts the metered usage from that allowance to calculate the remaining balance.

// Give 1 million monthly GTP-4 tokens to customer-1
const entitlement = await openmeter.subjects.createEntitlement('customer-1', {
  type: 'metered',
  featureKey: 'gpt_4_tokens',
  issueAfterReset: 1_000_000 // Issue 1 million tokens after each reset (starting now)
  usagePeriod: {
    interval: 'MONTH',
  },
  isSoftLimit: false // If balance falls to 0, access is denied
})

Above we created a metered entitlement for customer-1, granting them 1 million GPT-4 tokens every month starting now. The issueAfterReset property is used to define how many tokens to issue after each reset (at the start of each period), you can think of it as an initial balance for the entitlement. The usagePeriod defines the period in which you want to measure usage (usually same as the customer's billing cycle), which accepts an optional anchor time that defaults to now.

#3. Check Access

Verify that your customer has access to the feature by checking the entitlement's current value.

// Get the entitlement's current value
const value = await openmeter.subjects.getEntitlementValue(
  'customer-1',
  'gpt_4_tokens',
);
const { hasAccess, balance, usage, overage } = value;
 
if (!hasAccess) {
  return reply.status(402).send('purchase additional tokens');
}