> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt
> - v1: https://docs.paid.ai/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# Meters

> Create product-scoped meters from signal events and signal data.

Meters turn your signal stream into billable usage quantities. Use a meter when a
pricing line should count or sum a filtered set of signals instead of matching
one raw event name directly.

For example, a product might emit one `phone_call` signal for every call attempt,
but you may want separate pricing for:

* Completed calls where `call_completed = true`
* Completed call minutes, summed from `duration_minutes`

A meter defines that logic once, previews it against real signal data, and can
then be selected as the usage source for a pricing attribute.

## When to use a meter

Use direct signal-event pricing when every signal with an event name should bill
the same way. For example, every `chat_message` signal consumes one credit.

Use a meter when usage depends on signal `data` fields:

* Count only signals that match a condition, such as `call_completed = true`
* Sum a numeric field, such as `duration_minutes`
* Preview billable quantities before attaching the pricing rule to orders

> **Note**
>
> Meters read from signals. They do not replace customer or product attribution.
> Continue sending signals with the correct customer and product identifiers so
> Paid can resolve the usage to the right customer and order.

## Prerequisites

Before creating a meter, make sure you have:

1. A product in Paid with a stable external ID.
2. Signals flowing for that product. See [First signals](/documentation/getting-started/first-signals).
3. Consistent signal `data` fields for any metadata you want to filter or sum.
4. At least a few representative signals in the selected preview window.

If you want the meter to drive billing or credit consumption, configure the meter
before activating the orders that should use it.

## Step 1: Plan the signal data

Decide which signal event names and `data` fields the meter will use. Keep field
names stable across SDKs and services.

```json
{
  "eventName": "phone_call",
  "customer": { "externalCustomerId": "cus_acme" },
  "attribution": { "externalProductId": "voice_agent" },
  "data": {
    "call_completed": true,
    "duration_minutes": 12
  }
}
```

In this example:

* `call_completed` filters out missed, abandoned, or failed calls
* `duration_minutes` can be summed by a meter instead of counted as one event

## Step 2: Create the meter

1. In the Paid dashboard, go to **Meters**.
2. Click **Create meter**.
3. Select the product whose signals should feed the meter.
4. Enter a clear name, such as `Completed calls` or
   `Completed call minutes`.
5. Choose an operation:
   * **Count** counts matching signals.
   * **Sum** adds the value from a numeric signal `data` field.
6. Add filters:
   * Use **Event name** to select the signal event, such as
     `phone_call`.
   * Use **Data field** to filter on signal data, such as
     `call_completed = true`.
7. Set the preview window.
8. Confirm the previewed customers, quantity, and signal count look right.
9. Save the meter.

If no event names or data fields appear, send representative signals for the
selected product first, then reopen the meter builder.

## Step 3: Attach the meter to pricing

Once the meter previews correctly, attach it to the usage pricing that should
bill from that quantity.

1. Open the product or plan pricing configuration.
2. Add or edit a usage-based pricing attribute.
3. Set **Usage source** to **Meter**.
4. Select the meter you created for the same product.
5. Configure the pricing model:
   * For direct usage billing, set the price per metered unit.
   * For credit-backed usage, select prepaid credits and set the credit cost per
     metered unit.
6. Save the product or plan.
7. Create and activate orders after the pricing configuration is in place.

When a usage pricing attribute uses a meter, the meter output becomes the
quantity for that pricing line. Billing stores meter-backed usage as whole
units, so summed fields should represent whole billable units or be intentionally
rounded.

## Step 4: Verify the result

After saving the meter-backed pricing:

1. Send a small set of test signals with known values.
2. Reopen the meter and check the preview quantity.
3. Confirm the customer's product or order is active.
4. Review the customer's usage or credit balance after usage is processed.

For credit-backed products, the meter quantity is multiplied by the configured
credit cost. For example, if a meter returns `4` and the pricing rule costs `2`
credits per unit, the usage consumes `8` credits.

## Operational rules

**Meters are product-scoped.** A meter is configured for one product. Use it on
pricing attributes for that same product so preview and billing are scoped to the
same signal stream.

**Signal data types should stay consistent.** If a meter sums
`duration_minutes`, send it as a number on every signal. Avoid mixing strings
like `"12"` with numbers like `12`.

**Usage from a non-billable customer unit is left out.** Signals from a
[customer unit](/documentation/credits/customer-units-and-credit-caps#tracking-usage-without-billing-it)
set to `billable: false` are still stored and still match the meter, but the
pricing line leaves them out of its quantity, and the preview shows the quantity
without them.

**Missing fields do not match ordinary value filters.** If a filter expects
`call_completed = true`, signals without `call_completed` are excluded. Use
presence filters when you need to count whether a field exists.

**Preview before activating orders.** The preview is the fastest way to catch
wrong event names, missing metadata, or unexpected quantities.

**Meters can become locked.** Once a meter is referenced by active orders, Paid
prevents changes that would alter billing for those orders. Create a new meter
for new billing logic instead of editing a locked meter.

## Related guides

* [First signals](/documentation/getting-started/first-signals)
* [Credits](/documentation/credits/credits)
* [How credit balances work](/documentation/credits/how-credit-balances-work)
* [Analytics query cookbook](/documentation/analytics-api/query-cookbook#querying-signal-metadata)