Admin walkthrough — create a rule

Step-by-step click path from a fresh tenant to a working rule. Assumes you already enabled the module under /admin/modules → State Usergroup Rules.

Step 1 — Confirm the target usergroup exists

Open /admin/usergroups.

+------------------------------------------+
|  Usergroups                              |
+------------------------------------------+
|  Name              Status     Members    |
|  ----------------  ---------  ---------  |
|  customers-ca      Active     0          |
|  customers-ny      Active     0          |
|  wholesale         Active     12         |
+------------------------------------------+

If the group doesn't exist, create it first. Set:

• Name (e.g. customers-ca).
• Type: customer.
• Status: Active.

Save. Copy the UUID if you plan to create rules via the API.

Step 2 — Confirm the state exists

The rule form's state list comes from the states seeded for your store's countries. Open /admin/states and check that the state you want (e.g. California, code CA) is there. Add it if it's missing.

Step 3 — Open the rule list

Navigate to /admin/state-usergroup-rules.

+------------------------------------------------------------+
|  State usergroup rules                       + Add rule    |
+------------------------------------------------------------+
|  State name     State code   Usergroup      Auto-assign    |
|  -------------  ----------   -------------  -----------    |
|  (empty)                                                   |
+------------------------------------------------------------+

Empty list on a fresh tenant. The Add rule button is in the top right.

Step 4 — Fill the rule form

Click Add rule. A form opens above the list:

+-----------------------------------------------------------+
|  Add rule                                                 |
+-----------------------------------------------------------+
|  State      [California (CA)        v]                    |
|  Usergroup  [customers-ca (customer) v]                   |
|                                   [Add rule]  [Cancel]    |
+-----------------------------------------------------------+

Field-by-field:

• State: dropdown of seeded states, labelled "Name (CODE)". When your states span more than one country, the country code is appended so identical codes stay distinguishable. The rule stores the code and fills state_name from the selection.
• Usergroup: dropdown of every usergroup that isn't disabled. If your target isn't there, go back to step 1.

Click Add rule. The rule appears in the list immediately with Auto-assign: Yes. Creating the same state + usergroup pair again updates the existing rule instead of adding a duplicate.

Step 5 — Repeat for every state you care about

You typically end up with a handful of rules — one per state you want to segment by.

Tip: if you have many rules to create, post them via the API in a single shell loop rather than clicking through the UI:

for st in NY NJ CT MA PA; do
  curl -X POST https://YOUR_STORE.example.com/api/v1/admin/state-usergroup-rules \
    -H "Authorization: Bearer $ADMIN_JWT" \
    -H "Content-Type: application/json" \
    -d "{\"state_code\":\"$st\",\"state_name\":\"$st\",\"usergroup_id\":\"<uuid>\",\"auto_assign\":true}"
done

The API also accepts "auto_assign": false to store a rule without activating it (the admin form always creates active rules).

Step 6 — Confirm the list

Back at /admin/state-usergroup-rules, the list should now show every saved rule with its state name, code, usergroup and auto-assign status.