Create Rules

Rules tell Meterry how to convert raw usage JSON into billable charge items.

There are two rule set types in the Portal:

• Extractor rule sets read raw JSON, extract subjects and dimensions, and create charge items.
• Pricing rule sets rate charge items when extractor-attached pricing is not enough.

For stable high-volume metrics, prefer extractor charge items with attached pricing. Pricing rule sets are best for fallback matching, exceptions, and advanced formulas.

Create an extractor draft

Open Rules in the project sidebar.

1. Select Create extractor draft.
2. Enter a name.
3. Choose an extractor template if one matches your event shape, or keep a custom configuration.
4. Edit the configuration JSON.
5. Select Create extractor draft.

The extractor configuration usually contains:

• subject, for example a user, workspace, API key, or organization in the raw event;
• dimensions, such as provider, model, region, plan, or customer metadata;
• charge_item_extractors, which define metrics, quantities, units, and optional attached pricing.

What an extractor rule contains

An extractor rule is the contract between your raw event shape and Meterry’s normalized usage model. It has three main parts: subject, dimensions, and charge_item_extractors.

Subject

subject identifies the entity that produced the usage. Type and ID use the same path-first, default-second model:

• type_path and id_path read the subject pair from the raw event;
• default_type and default_id provide independent fallbacks when a path is missing, null, or empty;
• required decides whether an incomplete pair fails normalization or is omitted.

A dynamic subject type must be a string matching [a-z][a-z0-9_]{0,63}. A path value with the wrong JSON type or an invalid subject type is rejected rather than hidden by a default. Meterry never emits only one half of a subject pair.

Meterry extracts the subject so usage can be bound to a billing entity. In the Portal, Subject Routes map:

subject_type + subject_id -> billing_account_id

That route lets the runtime resolve which account should own the usage, which wallet should be debited, and which subject-level usage controls should be updated. Without a subject, Meterry can still extract analytics, but it cannot reliably attach the event to a payer account for realtime debit or account-level balance control.

Dimensions

dimensions are labels copied from the raw event into the normalized usage context. Common dimensions are provider, model, region, route, plan, environment, workspace, or customer metadata.

Dimensions are not usually the billing owner. They are query and grouping indexes for later analysis. In Usage explorer and reporting views, dimensions let you answer questions such as:

• how much did gpt-4.1 cost this week;
• which provider generated the most output tokens;
• how usage differs by region, plan, customer segment, or environment.

Keep dimensions stable and low-cardinality when possible. Use subject for billing ownership, and use dimensions for filtering, grouping, audit context, and pricing conditions.

Charge item extractors

charge_item_extractors turn the raw event into billable line items. Each extractor creates one metric, such as prompt_tokens, output_tokens, requests, tool_calls, or agent_minutes.

A charge item extractor usually defines:

• metric, the stable key used for reporting and pricing;
• path or quantity_expr, the source of the quantity;
• type and unit, such as number of token, request, call, minute, or byte;
• required, skip_if_missing, or defaults, which decide how missing values behave;
• optional currency, unit_price_expr, and amount_expr, which attach direct pricing for stable metrics.

At runtime, Meterry reads the event with compiled accessors, extracts the subject and dimensions, then runs each charge item extractor. If attached pricing exists, the item can be rated on the hot path without scanning a fallback pricing rule set. This is the preferred mode for stable high-volume metrics such as token counts and request counts.

Use quantity_expr for calculated quantities, such as a fixed dec('1') request item. Use decimal helpers such as dec, dec_mul, and dec_div for money-sensitive calculations.

Sparse, request-specific metrics can be reported with x-billing.items instead of being configured as extractor charge items. In hybrid events, valid x-billing.items for a metric take priority over extractor-generated items for the same metric.

For the full runtime order, metric context behavior, and decimal expression syntax, read How Extraction Runs.

When an item represents an analytics fact rather than a customer charge, attach control.analytics_only so the item stays queryable but never reaches the wallet. For the full control block, see Charge-Item Control; for the analytics-only flag specifically, see Analytics-Only.

Example event

{
  "type": "response",
  "provider": "openai",
  "usage": {
    "model": "gpt-4.1",
    "prompt_tokens": 1200,
    "output_tokens": 300
  },
  "meta": {
    "user_id": "u_01"
  }
}

For this event, a good first extractor rule should:

• use meta.user_id as the subject ID;
• keep provider and usage.model as dimensions;
• create charge items for prompt tokens, output tokens, and optionally requests.

Create a pricing draft

Create a pricing draft when you need fallback rating for charge items that are not already rated by extractor-attached pricing.

1. Select Create pricing draft.
2. Enter a name.
3. Add pricing rule JSON.
4. Select Create pricing draft.

Pricing rules can match by metric and other dimensions. Metric-specific rules keep fallback matching narrow and easier to reason about.

Drafts are not active

Creating a draft stores the rule set for review. It does not change production ingestion. Publish the draft after testing.