Billing

Meters

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

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.
  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.

1{
2  "eventName": "phone_call",
3  "customer": { "externalCustomerId": "cus_acme" },
4  "attribution": { "externalProductId": "voice_agent" },
5  "data": {
6    "call_completed": true,
7    "duration_minutes": 12
8  }
9}

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.

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.