Skip to main content

​
Overview

Meters define how to aggregate events into billable usage. They specify which events to count and how to calculate the quantity.

​
The Meter Object

​
id
string
required
Unique identifier
​
name
string
required
Meter name
​
slug
string
required
URL-friendly identifier
​
filter
object
required
Event filter clause
​
aggregation
enum
required
Aggregation function: count, sum, avg, max, or unique_count
​
aggregate_field
string
Property to aggregate (required for sum/avg/max)
​
organization_id
string
required
Organization ID
​
is_archived
boolean
required
Whether meter is archived
​
metadata
object
Custom metadata
​
created_at
string
required
Creation timestamp

​
List Meters

cURL
curl -X GET "https://api.polar.sh/v1/meters" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
organization_id
string
Filter by organization
​
query
string
Filter by name
​
is_archived
boolean
Filter archived meters
​
metadata
object
Filter by metadata

​
Get Meter

cURL
curl -X GET "https://api.polar.sh/v1/meters/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
Meter ID

​
Create Meter

cURL
curl -X POST "https://api.polar.sh/v1/meters" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests",
    "slug": "api_requests",
    "filter": {
      "type": "and",
      "clauses": [
        {
          "type": "property",
          "property": "name",
          "operator": "eq",
          "value": "api_request"
        }
      ]
    },
    "aggregation": "count",
    "organization_id": "org_123"
  }'

​
Request Body

​
name
string
required
Meter name
​
slug
string
URL-friendly slug (auto-generated if not provided)
​
filter
object
required
Filter clause to match events
​
aggregation
enum
required
How to aggregate: count, sum, avg, max, unique_count
​
aggregate_field
string
Event property to aggregate (required for sum/avg/max)
​
organization_id
string
Organization ID (required unless using org token)
​
metadata
object
Custom metadata

​
Update Meter

cURL
curl -X PATCH "https://api.polar.sh/v1/meters/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requests (Updated)",
    "is_archived": false
  }'

​
Path Parameters

​
id
string
required
Meter ID

​
Request Body

​
name
string
Update name
​
is_archived
boolean
Archive/unarchive meter
​
metadata
object
Update metadata

​
Get Meter Quantities

cURL
curl -X GET "https://api.polar.sh/v1/meters/{id}/quantities" \
  -H "Authorization: Bearer polar_pat_..."
Get aggregated quantities for a meter over time.

​
Path Parameters

​
id
string
required
Meter ID

​
Query Parameters

​
start_timestamp
string
required
Start of time range
​
end_timestamp
string
required
End of time range
​
interval
enum
required
Time interval: hour, day, week, or month
​
customer_id
string
Filter by customer
​
timezone
string
default:"UTC"
Timezone for aggregation (e.g., America/New_York)

​
Delete Meter

cURL
curl -X DELETE "https://api.polar.sh/v1/meters/{id}" \
  -H "Authorization: Bearer polar_pat_..."
Deleting a meter will affect any products using metered pricing based on this meter.

​
Examples

​
Count Events

curl -X POST "https://api.polar.sh/v1/meters" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "slug": "api_calls",
    "filter": {
      "type": "property",
      "property": "name",
      "operator": "eq",
      "value": "api_request"
    },
    "aggregation": "count",
    "organization_id": "org_123"
  }'

​
Sum Property Values

curl -X POST "https://api.polar.sh/v1/meters" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Transfer (GB)",
    "slug": "data_transfer_gb",
    "filter": {
      "type": "property",
      "property": "name",
      "operator": "eq",
      "value": "data_transfer"
    },
    "aggregation": "sum",
    "aggregate_field": "bytes",
    "organization_id": "org_123"
  }'

​
Complex Filter

curl -X POST "https://api.polar.sh/v1/meters" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium API Calls",
    "filter": {
      "type": "and",
      "clauses": [
        {
          "type": "property",
          "property": "name",
          "operator": "eq",
          "value": "api_request"
        },
        {
          "type": "property",
          "property": "tier",
          "operator": "eq",
          "value": "premium"
        }
      ]
    },
    "aggregation": "count",
    "organization_id": "org_123"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us