Admin walkthrough — test and preview

Before relying on a rule on a live tenant, dry-run it against a test customer. The platform doesn't ship a "preview which usergroups would apply" tool, but the equivalent click path is straightforward.

Method A — Test customer in production

Safest for low-volume tenants. You spin up a throwaway customer and watch the assignment land.

1. Open /admin/users → New user. Pick customer type. Save with an email like [email protected].
2. Open the new customer's profile.
3. Add an address. Enter:
   • State: the state code your rule maps (e.g. CA).
   • Other fields: any plausible values. Save.
4. Refresh the profile and look at the usergroups. The target group should be listed. If it is, the rule fires. (The assignment runs in the background right after the address saves, so give it a second.)
5. Delete the test customer to keep your data clean.

+--------------------------------------------------+
|  Customer: [email protected]            |
+--------------------------------------------------+
|  Usergroups                                      |
|    [x] customers-default                         |
|    [x] customers-ca     <-- auto-assigned        |
|                                                  |
|  Addresses                                       |
|    100 Market Street, San Francisco / CA         |
+--------------------------------------------------+

Method B — Stage with auto_assign=false

For larger tenants where creating a test customer is awkward.

1. Create the rule through the API with "auto_assign": false. The row is saved but inactive — no live customers are affected.
2. Verify the rule is visible in /admin/state-usergroup-rules with Auto-assign: No.
3. When you're ready, POST /api/v1/admin/state-usergroup-rules again with the same state_code + usergroup_id and "auto_assign": true. The existing rule is updated in place.
4. Wait for the next address create/update on a live customer in that state, then verify they got the group.
5. If anything looks wrong, post the pair again with "auto_assign": false, or delete the rule.

Method C — Smoke via API

Pure API path; no UI clicks. Best if you script tenant set-up.

# Create test user
USER=$(curl -s -X POST https://YOUR_STORE.example.com/api/v1/admin/users \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{"email":"[email protected]","type":"customer","name":"Smoke"}' \
  | jq -r .id)

# Create address with target state
curl -X POST https://YOUR_STORE.example.com/api/v1/admin/users/$USER/addresses \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{"first_name":"Jane","last_name":"Doe","address_line1":"100 Market Street","city":"San Francisco","state":"CA","postal_code":"94105","country":"US"}'

# Check the assignment landed
curl -s https://YOUR_STORE.example.com/api/v1/admin/users/$USER \
  -H "Authorization: Bearer $ADMIN_JWT" \
  | jq '.usergroups[].name'

Expect output to include the mapped group. If it doesn't, walk through Troubleshooting.

What gets logged

Every assignment writes one info log line:

INFO state usergroup auto-assigned user_id=<uuid> usergroup_id=<uuid> state_code=CA

Tail your backend logs and filter on state usergroup while running your test to see the assignment as it happens.

What if you need to UN-assign?

The platform doesn't auto-unassign when a customer changes state. Manual options:

• Bulk drop: DELETE FROM usergroup_links WHERE usergroup_id = '<old-group-uuid>' AND user_id IN (SELECT id FROM users WHERE ...).
• Per-customer: open /admin/users/<id> and remove the group.

Plan for this on day one: if your rule is "move customers to the right state group when they update their address", you also need an unassign step. State Usergroup Rules is additive only.