Subject Routes

Subject routes connect usage producers to the account that should pay for them. Routes are project-scoped, so the same subject_type + subject_id can route to different accounts in different projects.

A subject is any entity that can produce usage:

• user/u_01
• workspace/ws_123
• api_key/key_abc
• agent/agent_789

An account is the payer. A route says:

subject_type + subject_id -> billing_account_id

The full lookup scope is:

project_id + subject_type + subject_id + currency

Why subject routes matter

Many SaaS products have many usage producers under one payer.

Example:

Organization account: acct_org_001
  user/u_01 -> acct_org_001
  user/u_02 -> acct_org_001
  agent/agent_123 -> acct_org_001

Each subject can have independent usage controls inside the project, while spend still debits the same organization wallet in that project.

Bind a subject

Open an account and switch to Subject routing.

1. Enter the account ID if it is not already selected.
2. Choose a subject type such as user, workspace, api_key, or agent.
3. Enter the subject ID from your application.
4. Select Bind subject.

Saved bindings appear in the subject routing table.

Add usage controls

From a subject binding, select Usage controls.

Create a usage control to set a realtime limit for that subject.

Limit types:

• Amount: limit total rated amount for a currency.
• Unit: limit usage by unit, such as tokens.
• Metric: limit a specific metric, such as input_tokens, by quantity or amount.

Common settings:

• Limit: the maximum amount or quantity.
• Period: hour, day, week, or month.
• Timezone: optional billing window timezone.
• Action: usually block when the limit is exceeded.

How events use routes

For routing to work, your usage event must enter the same project and produce the same subject type and subject ID that you bound in the Portal.

For example, if the route is:

user/u_01 -> acct_org_001

then the extractor rule should extract:

{
  "subject_type": "user",
  "subject_id": "u_01"
}

When a rated event arrives, Meterry resolves the payer account inside the event project, debits the matching wallet in that project, and updates usage control counters for that subject.