Create Usage Control Rule

Creates a project-scoped usage control route from a usage subject to a real billing account. Optional limits[] entries define range limits for the same subject.

POST /v1/projects/:project_id/usage-control-rules

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Path Parameters

Field	Required	Description
`project_id`	Yes	Project that owns the usage-control route and range limits. The `billing_account_id` must belong to this project.

Request Body

{
  "billing_account_id": "acct_xxx",
  "subject_type": "user",
  "subject_id": "user_123",
  "currency": "USD",
  "limits": [
    {
      "currency": "USD",
      "metric_scope": "tokens",
      "measure": "quantity",
      "period": "week",
      "limit_amount": "1000000",
      "timezone": "Asia/Shanghai",
      "action": "block",
      "webhook_event": "usage.weekly_tokens_exceeded"
    },
    {
      "currency": "USD",
      "metric_scope": "amount",
      "measure": "amount",
      "period": "month",
      "limit_amount": "500.00",
      "timezone": "Asia/Shanghai",
      "action": "block",
      "webhook_event": "usage.monthly_amount_exceeded"
    }
  ]
}

Top-Level Fields

Field	Required	Description
`billing_account_id`	Yes	Real billing account ID in the same project to debit.
`subject_type`	Yes	Usage-producing subject type.
`subject_id`	Yes	Usage-producing subject ID.
`currency`	No	Default currency. Used when `limits[].currency` is empty.
`limits`	No	Range limit list. May be empty when you only need the billing route.

`limits[]` Fields

Field	Required	Description
`currency`	Conditionally	Limit currency. Uses top-level `currency` when empty.
`metric_scope`	No	Business scope being limited, such as `tokens`, `requests`, `tool_calls`, or `amount`.
`measure`	No	Counting method for the limit. Defaults to `quantity` unless `metric_scope` is `amount`, in which case it defaults to `amount`.
`period`	Yes	Window period. Supports `hour`, `day`, `week`, `month`, `lifetime`, the aliases `daily`, `weekly`, `monthly`, and custom counts or durations like `7d`, `5h`, `5 day`, `2 week`, or `5 month`. All anchored windows start from the usage-limit anchor. `lifetime` never resets.
`limit_amount`	Yes	Limit value. Must be greater than `0`. Use a JSON string for decimal precision.
`timezone`	No	Time zone used for window calculations. Defaults to UTC. Ignored for `period=lifetime`.
`action`	No	Suggested control action when exceeded, for example `block` or `warn`.
`webhook_event`	No	Business event name to emit or handle when the limit is exceeded.

MetricScope vs Measure

metric_scope names the business scope being limited, such as tokens, requests, tool_calls, or amount. measure names the accounting method used for that limit, usually quantity for count-based usage or amount for money-based usage.

In practice:

metric_scope = tokens, measure = quantity means “limit token usage”.
metric_scope = amount, measure = amount means “limit spend”.

Response

{
  "rule_account": {
    "id": "racct_xxx",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "billing_account_id": "acct_xxx",
    "subject_type": "user",
    "subject_id": "user_123",
    "status": "active",
    "created_at": 1782720000,
    "updated_at": 1782720000
  },
  "limits": [
    {
      "id": "racl_xxx",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "rule_kind": "subject_route",
      "rule_id": "racct_xxx",
      "currency": "USD",
      "metric_scope": "tokens",
      "measure": "quantity",
      "period": "week",
      "limit_amount": "1000000",
      "timezone": "Asia/Shanghai",
      "action": "block",
      "webhook_event": "usage.weekly_tokens_exceeded",
      "status": "active",
      "created_at": 1782720000,
      "updated_at": 1782720000
    }
  ]
}

Behavior

After the rule is created, Meterry:

persists the billing route and limit configuration;
syncs the realtime route cache;
attributes later rated charge items for the subject to billing_account_id;
debits the realtime virtual wallet by currency;
accumulates range limit usage by metric_scope, measure, period, and timezone.

When the subject route already selects a published Usage Limit Plan, these limits[] entries are custom additions: Billing evaluates the Plan limits first, then advances the custom limits for the same event. A custom rule does not detach the selected Plan.

Notes

This endpoint currently creates routes. A project can have only one active route for the same subject_type and subject_id.
action=block is a control suggestion after a limit is exceeded. It does not prevent a usage event that has already entered Meterry from being accounted.
Multi-currency charge items are routed and debited by currency.
All anchored windows, including month, 1 month, 7d, 5h, 5 day, 2 week, and 5 month, start from the subject route’s usage-limit anchor. The first reset is anchor time plus the configured period; Plan edits and publishes keep the same anchor.