Settings reference
The module has no config_schema fields. All operational state lives in the state_usergroup_rules table.
Per-rule fields
| Field | Type | Purpose |
|---|---|---|
state_code | text (up to 10 chars) | State / region code — CA, NY, TX, ... Matched exactly against the address's state. |
state_name | text | Display label only. The admin form fills it from the selected state; the API accepts any text. |
usergroup_id | UUID | Target usergroup. The admin UI offers a dropdown of usergroups; the service validates existence on insert (SELECT EXISTS FROM usergroups WHERE id = $1). |
auto_assign | boolean | Default true. When true, the rule fires on address create/update. When false (API only), the rule is dormant — useful for staging changes without applying them. |
The unique constraint is (state_code, usergroup_id) — one rule per pair. Posting an existing pair again updates that row's state_name + auto_assign.
Privileges
| Privilege | Grants |
|---|---|
view_vendors | Read rules. |
manage_vendors | Read, create/upsert, delete rules. |
There is no separate manage_state_rules privilege.
Endpoints
GET /api/v1/admin/state-usergroup-rules— list all rules with usergroup names joined.POST /api/v1/admin/state-usergroup-rules— create or upsert.DELETE /api/v1/admin/state-usergroup-rules/{id}— remove a single rule.
There is no per-rule update endpoint — POST handles the upsert.
Recommendations
- Stage risky rules with
auto_assign=falsethrough the API while you smoke-test the wiring. Flip totrueonce verified — avoids accidentally assigning groups to live customers during dry-runs. - Don't use this module for non-state segmentation (e.g. by city, by postal-code range). Squeezing those into state-keyed rules will get messy.
- Pair every state-usergroup rule with something on the receiving usergroup — a price tier, a shipping or payment restriction, a visibility rule. A usergroup that does nothing other than "exists" is just noise.
- The natural rule count is small (a few per state you segment by). If you find yourself with hundreds of rules, you're probably stretching the model — reconsider.