FAQ

Does the rule apply to existing customers?

No. The rule fires forward only — on address create/update. Existing addresses are not retroactively scanned. To back-fill, either re-save every address through the API (which triggers the service) or run a one-off SQL INSERT … ON CONFLICT DO NOTHING into usergroup_links joining user_addresses with state_usergroup_rules.

Can I map one state to multiple groups?

Yes. Add as many rules per state as you need; each one fires independently. The unique constraint is (state_code, usergroup_id), so the SAME state-group pair can't be duplicated, but a state can map to N different groups.

Can I have one group from multiple states?

Yes. Define CA → wholesale, NY → wholesale, TX → wholesale. Customers from any of those states land in the same group.

Does the rule remove the OLD group when a customer moves states?

No. The rule is additive — it only assigns. A customer who lived in CA and moved to NY keeps the CA group unless you manually trim it. If exclusive membership matters, wire an unassign step at the address-write site.

What happens if I delete a usergroup but leave the rule?

The next time the rule fires, the insert into usergroup_links can fail. The address write still commits; the customer simply isn't grouped. Symptoms: a "missing group" looks like the rule didn't fire. Fix by deleting the orphaned rule.

Can I delete a rule?

Yes — click Delete in /admin/state-usergroup-rules or call DELETE /api/v1/admin/state-usergroup-rules/<id>. Deleting the rule does NOT remove already-assigned usergroup_links rows. If you want a hard reset, also DELETE FROM usergroup_links WHERE usergroup_id = '<group>' (be careful — that removes everyone, not just rule-derived assignments).

Does the rule fire on every page view or only on address change?

Only on address create/update. The rule is NOT evaluated on every login or page request. Once the group is on the user, it stays until manually removed.

How do I roll out a rule safely?

Two options:

1. Create it through the API with auto_assign=false. Verify the row is correct. Then post the same pair with auto_assign=true.
2. Create it for a single low-traffic state first and watch for surprises before rolling out to your biggest states.

Why didn't the rule fire for an address entered at checkout?

The rule runs from the address-book service (CreateAddress / UpdateAddress). An address that only exists on an order isn't saved through that path. Ask customers to save the address to their account, or add an ApplyStateUsergroups call to the path you use.

Can I trigger the rule from the admin panel manually?

Not currently. The only way to re-fire is to re-save the customer's address with its state. A "re-apply rules" button is on the roadmap but not shipped.

Does the rule work for any country?

Yes, as long as addresses in that country carry a state or region value. The rule matches the address's state against the rule's code; the admin form offers the states seeded for every country your store uses. Addresses without a state never match.

What's the difference vs usergroups directly?

Usergroups are a generic permission/segment primitive. State Usergroup Rules is a thin auto-assign layer on top that says "when an address with state X is saved, also add group Y". You CAN manage usergroups without this module — you just have to assign customers manually. The module automates the by-state case.

Does it integrate with price tiers / shipping / payment methods?

Indirectly. The rule's job ends at "customer is in usergroup G". Downstream features (usergroup-scoped price tiers, shipping-method and payment-method usergroup restrictions, product and banner visibility, CRM segments) read the usergroup and apply their own logic. Wiring is your responsibility — the rule is just the trigger.

Is there a webhook when a rule fires?

No. The platform doesn't emit an event when a state-usergroup auto-assignment happens. Only a log line.

Can the rule downgrade a group (lower-priority)?

No concept of priority in this module. The rule is binary: state matches → group added. Priority logic, if needed, lives in the consumer (for example the price-tier resolution).