Manage Subject Routes with Go

Subject routes connect usage subjects to billing accounts:

project_id + subject_type + subject_id -> account_id

The usage processor uses this route to decide which account and wallet should receive realtime usage debits and usage-limit updates.

Create a Subject Route

route, err := client.Manager.BindSubjectForProject(ctx, "proj_gateway", types.BindAccountSubjectRequest{
  AccountID:   "acct_001",
  SubjectType: "org",
  SubjectID:   "org_001",
})
if err != nil {
  return err
}

fmt.Println(route.ID)

EffectiveFrom can be set when the route should start at a specific Unix timestamp.

route, err := client.Manager.BindSubjectForProject(ctx, "proj_gateway", types.BindAccountSubjectRequest{
  AccountID:     "acct_001",
  SubjectType:   "user",
  SubjectID:     "user_123",
  EffectiveFrom: 1781222400,
})

List Subject Routes

routes, err := client.Manager.ListAccountSubjectsForProject(ctx, "proj_gateway", "acct_001")
if err != nil {
  return err
}

for _, route := range routes {
  fmt.Println(route.SubjectType, route.SubjectID)
}

Create Route and Limits Together

CreateUsageControlRuleForProject also ensures the subject route exists before creating limits. Use it when a subject route and limits should be configured in one operation.

rule, err := client.Manager.SetSubjectRouteAndUsageLimitsForProject(ctx, "proj_gateway", types.CreateUsageControlRuleRequest{
  BillingAccountID: "acct_001",
  SubjectType:      "org",
  SubjectID:        "org_001",
  Currency:         "USD",
  Limits: []types.CreateRuleAccountLimitRequest{{
    MetricScope: "tokens",
    Period:      "month",
    LimitAmount: decimal.RequireFromString("1000000"),
  }},
})

Supported Methods

Method	Description
BindSubject	Creates a subject route. Uses req.ProjectID when set.
BindSubjectForProject	Creates a subject route under /projects/:project_id/account-subjects.
ListAccountSubjects	Lists active routes for an account without an explicit project path.
ListAccountSubjectsForProject	Lists active routes for an account under /projects/:project_id/account-subjects.
SetSubjectRouteAndUsageLimits	Creates or ensures a route and attaches usage limits.
SetSubjectRouteAndUsageLimitsForProject	Project-scoped version of route plus limits creation.