Getting started

1. Create the usergroups first

Open /admin/usergroups. Create the groups you want the rules to assign — e.g. customers-ca, customers-northeast, customers-tx. The rule needs the usergroup to exist before you can map a state to it.

If you're using usergroups for price tiers or visibility, do that wiring BEFORE turning on the module — otherwise users get assigned to a group that does nothing yet.

2. Make sure the states exist

The rule form lists the states seeded for your store's countries (/admin/states). If a state or region you need is missing, add it there first.

3. Enable the module

/admin/modules → State Usergroup Rules → toggle ON.

There are no config_schema fields. The module is binary on/off.

4. Define the rules

Open /admin/state-usergroup-rules → Add rule:

• Pick a state (e.g. California (CA)).
• Pick a target usergroup.
• Save.

Rules created in the admin are active (auto_assign = true). Repeat for every state-to-group mapping.

5. Test the assignment

To confirm the wiring:

1. Create a test customer.
2. Add an address with state = CA (assuming you mapped CA → group X).
3. Open the customer's profile — group X should appear in their usergroups.

If it doesn't:

• Confirm the module is enabled.
• Confirm the address's state value is exactly the rule's state code (CA, not California or ca).
• Check backend logs for state-usergroup-rules module disabled for tenant (means the module check returned false).

6. Existing customers

The rule fires on address create/update. Customers whose addresses were captured BEFORE you defined the rules are NOT auto-assigned retroactively. Two paths:

• Re-save the addresses: any address update fires ApplyStateUsergroups. A script that touches every address through the API triggers a back-fill.
• Hand-assign: open each customer and add the group manually. Tedious but fine for small tenants.

Privileges

The rule routes sit in the admin vendor-management privilege group: reading rules requires view_vendors (or manage_vendors), creating and deleting them requires manage_vendors.