Meters

A meter watches a stream of events you send (api_call, image_render, seat_used) and aggregates them per customer per billing period. Each meter has:

• Slug: your short identifier (api_calls, image_renders).
• Event name: which events feed the meter.
• Aggregation: one of sum, count, max, last, unique_count.
• Value property: optional. When the aggregation is sum or max, this is the field on the event payload to pull the number from.
• Filter: optional. A JSON match shape that decides whether an incoming event applies.

Create meters from Products → Meters.

Hit POST /events/ingest whenever a unit of work happens. Batch up to 500 events per call. Each event matches against your active meters and increments the right customer's balance.

curl -X POST https://api.meridapay.com/events/ingest \
  -H "Authorization: Bearer $MERIDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "name": "api_call",
        "external_customer_id": "user_123",
        "value": 1,
        "metadata": { "endpoint": "/v1/render", "region": "us-east" },
        "external_id": "req_abc123"
      }
    ]
  }'

{ "inserted": 1, "duplicates": 0 }

Pass external_id on every event and Merida treats repeats with the same external_id as duplicates. Pair that with an Idempotency-Key header on the request and your ingestion is safe to retry from the queue.

On a product's entitlements, set feature_type: METERED and point at the meter. When a customer buys that product, every cycle's allowance is credited to their balance against this meter.

• allowance_type: FIXED: a hard cap per period.
• allowance_type: UNLIMITED: no cap, useful for usage tracking without limits.
• rollover_enabled: carry unused balance into the next period, optionally capped at rollover_cap.

See Entitlements for the full entitlement model.

Two ways:

• POST /check: fast yes/no gate before the work runs. Returns allowed, plus the resolved limit and remaining.
• GET /customers/{id}/balances: every meter for the customer in the current period.

curl -X POST https://api.meridapay.com/check \
  -H "Authorization: Bearer $MERIDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "user_123",
    "feature_key": "api_calls",
    "value": 1
  }'

{
  "allowed": true,
  "feature_key": "api_calls",
  "feature_type": "METERED",
  "balance": 9588,
  "limit": 10000,
  "consumed": 412,
  "remaining": 9588,
  "reason": "within_limit"
}