Where it lives
Open the organization switcher → Manage (or Invite members), then Team. Custom Roles is the first block. Modal id:create-role-modal.
Custom Roles


Custom Roles — empty state with Create Role
When roles exist, the table columns are:
Create Custom Role
The dialog title is Create Custom Role. Subtitle: Define a custom role with specific permissions for your team members.

Create Custom Role — name, description, and every permission checkbox
Fields
A footer line appears after the first selection: 1 permission selected / N permissions selected.
Buttons: Cancel, Create Role.
Toasts: Role created successfully / Failed to create role. Duplicate name: A role with this name already exists. (
ROLE_NAME_EXISTS).
Permission checkboxes
These are the only checkboxes in the dialog — 16 scopes, two columns. Each Read row uses the description View and read information. Each Write row uses Create, update, and delete. Labels come fromformatScopeLabel (first letter of each segment capitalized; underscores become spaces).
There are no separate checkboxes for orders, printers, billing, webhooks, automations, or brands.


The rest of the grid — Shipping rules, Shipments, and All
1
Open the dialog
Click Create Role or Create Your First Role.
2
Name the role
Fill Role Name *. Description is optional.
3
Toggle permissions
Check the scopes this role should have, or click Select All.
4
Create Role
Click Create Role. The role appears in the table.
Edit Custom Role
Edit (or a row click) opens the same dialog with title Edit Custom Role. Subtitle: Update role permissions for your team members. The submit button is Update Role. Fields and checkboxes are the same as create. Toasts: Role updated successfully / Failed to update role. Duplicate name still returnsROLE_NAME_EXISTS.
Delete Role
Delete opens Delete Role. Subtitle: You are about to delete role “{name}”. Description: This will unassign the role from 1 member. / This will unassign the role from N members. Type the confirm text shown (role "NAME" in uppercase). Delete stays disabled until it matches.
Confirming unassigns the role from its members. Toasts: Role deleted successfully / Failed to delete role.
ROLE_IN_USE (This role is assigned to members and cannot be deleted.) exists in error copy, but the delete handler unassigns members instead of refusing. Document the dialog you see: unassign, then delete.Related
- Invite team members — assign the role on invite or later.
- Create an API token — the same 16 scopes on tokens.
- Team and invitations — documentation for this tab.