Bind Subject Route

Creates a project-scoped subject route. A subject route maps one usage-producing subject, such as a user, API key, workspace, or agent, to the billing account that should own and pay for its rated usage.

POST /v1/projects/:project_id/account-subjects

Authentication

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

Requires accounts write access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the account and subject route.

Request Body

{
  "account_id": "acct_org_001",
  "subject_type": "user",
  "subject_id": "user_123",
  "effective_from": 1782720000
}

Fields

Field	Required	Description
account_id	Yes	Billing account ID in the same project.
subject_type	Yes	Usage-producing subject type, for example user, workspace, api_key, or agent.
subject_id	Yes	Usage-producing subject ID from your application.
effective_from	No	Unix timestamp when the route becomes effective. Defaults to the current server time.

Example

curl -X POST 'http://127.0.0.1:8080/v1/projects/proj_gateway/account-subjects' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "acct_org_001",
    "subject_type": "user",
    "subject_id": "user_123"
  }'

Response

{
  "id": "asub_xxx",
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "account_id": "acct_org_001",
  "subject_type": "user",
  "subject_id": "user_123",
  "effective_from": 1782720000,
  "created_at": 1782720000
}

Behavior

After the route is created, Meterry can resolve future rated usage events for the same project_id + subject_type + subject_id to account_id. The route is also synced to the realtime route cache when realtime wallet debit is enabled.

Notes

• Subject routes are project-scoped. The same subject_type + subject_id can route to different accounts in different projects.
• A usage event must extract the same subject type and subject ID for the route to match.
• Use Create Usage Control Rule when you also need range limits for the subject.