Saleor Customer and Staff Management

Before writing code

Fetch live docs:

Web-search site:docs.saleor.io customers accounts registration for customer account model and registration flow
Web-search site:docs.saleor.io staff users permissions groups for staff management and permission system
Web-search site:docs.saleor.io authentication JWT tokens for authentication flow and token handling
Fetch https://docs.saleor.io/docs/developer/users and review User model, addresses, and account operations
Web-search site:docs.saleor.io permission groups MANAGE_PRODUCTS MANAGE_ORDERS for the full list of available permissions

Customer Model

Saleor uses a single User entity for both customers and staff. The isStaff flag distinguishes between them.

Field	Description
`id`	Unique user identifier
`email`	Email address (unique, used for login)
`firstName`	Customer first name
`lastName`	Customer last name
`isActive`	Whether the account is enabled
`isStaff`	Whether the user has dashboard access
`dateJoined`	Account creation timestamp
`lastLogin`	Most recent login timestamp
`metadata`	Public key-value metadata
`privateMetadata`	Staff-only key-value metadata
`languageCode`	Preferred language
`defaultShippingAddress`	Default shipping address
`defaultBillingAddress`	Default billing address

Customer Registration and Login

Registration Flow

Step	Mutation	Description
1. Register	`accountRegister`	Create account with email and password
2. Confirm email	`confirmAccount`	Verify email with token from confirmation email
3. Active account	--	Account is active after confirmation

Registration Input

Field	Required	Description
`email`	Yes	Customer email address
`password`	Yes	Account password
`firstName`	No	First name
`lastName`	No	Last name
`redirectUrl`	Yes	URL for email confirmation link
`channel`	Yes	Channel slug for channel-specific registration
`languageCode`	No	Preferred language for communications
`metadata`	No	Initial metadata key-value pairs

Login Flow

Step	Mutation	Description
1. Obtain tokens	`tokenCreate`	Provide email + password; returns JWT access and refresh tokens
2. Use access token	--	Include in `Authorization: Bearer <token>` header
3. Refresh token	`tokenRefresh`	Exchange refresh token for new access token
4. Verify token	`tokenVerify`	Check if a token is still valid

JWT Authentication Flow

Token Type	Lifetime	Purpose
Access token	Short-lived (configurable, default ~5 min)	Authenticate API requests
Refresh token	Long-lived (configurable)	Obtain new access tokens
CSRF token	Per-session	Protect against cross-site request forgery

Token Mutations

Operation	Mutation	Notes
Login	`tokenCreate`	Returns `token`, `refreshToken`, `csrfToken`
Refresh	`tokenRefresh`	Requires `refreshToken`; returns new `token`
Verify	`tokenVerify`	Returns `isValid` and decoded payload
Deactivate all	`tokensDeactivateAll`	Invalidate all tokens for the user

Fetch live docs for token expiration configuration and any changes to the JWT authentication model.

Customer Addresses

Each customer can store multiple addresses with defaults for shipping and billing:

Field	Description
`firstName`	Address first name
`lastName`	Address last name
`companyName`	Optional company name
`streetAddress1`	Primary street address
`streetAddress2`	Additional address line
`city`	City name
`postalCode`	Postal or ZIP code
`country`	ISO 3166-1 alpha-2 country code
`countryArea`	State or province
`phone`	Phone number
`isDefaultShippingAddress`	Default for shipping
`isDefaultBillingAddress`	Default for billing

Address Mutations

Operation	Mutation	Notes
Create address	`accountAddressCreate`	Customer self-service
Update address	`accountAddressUpdate`	Customer self-service
Delete address	`accountAddressDelete`	Customer self-service
Set default	`accountSetDefaultAddress`	Set shipping or billing default
Admin create	`addressCreate`	Staff creating address for a customer
Admin update	`addressUpdate`	Staff updating customer address
Admin delete	`addressDelete`	Staff deleting customer address

Staff Users vs Customers

Aspect	Customer	Staff
`isStaff`	`false`	`true`
Dashboard access	No	Yes
API scope	Storefront queries, own account	Admin queries, assigned permissions
Creation	`accountRegister` or `customerCreate`	`staffCreate`
Permissions	None (implicit storefront access)	Assigned via permission groups

Staff Management Mutations

Operation	Mutation	Notes
Create staff	`staffCreate`	Set email, permissions, groups
Update staff	`staffUpdate`	Modify details and permissions
Delete staff	`staffDelete`	Remove staff user

Permission Groups

Permission groups bundle permissions and assign them to staff users:

Operation	Mutation
Create group	`permissionGroupCreate`
Update group	`permissionGroupUpdate`
Delete group	`permissionGroupDelete`

Key Permissions

Permission	Grants Access To
`MANAGE_PRODUCTS`	Products, categories, collections, product types
`MANAGE_ORDERS`	Orders, fulfillments, draft orders
`MANAGE_USERS`	Customer accounts and staff users
`MANAGE_STAFF`	Staff accounts and permission groups
`MANAGE_DISCOUNTS`	Vouchers and promotions
`MANAGE_SHIPPING`	Shipping zones and methods
`MANAGE_CHANNELS`	Channel configuration
`MANAGE_CHECKOUTS`	Checkout operations
`MANAGE_APPS`	App installation and configuration
`MANAGE_SETTINGS`	Site-wide settings
`MANAGE_TRANSLATIONS`	Content translations
`HANDLE_PAYMENTS`	Payment processing and transactions
`MANAGE_GIFT_CARD`	Gift card creation and management
`MANAGE_PAGE_TYPES_AND_ATTRIBUTES`	Page types and attributes

Fetch live docs for the complete PermissionEnum -- additional permissions may exist for plugins and newer features.

Account Management Mutations

Operation	Mutation	Actor
Request password reset	`requestPasswordReset`	Customer
Set new password	`setPassword`	Customer (with token)
Change password	`passwordChange`	Customer (authenticated)
Request email change	`requestEmailChange`	Customer
Confirm email change	`confirmEmailChange`	Customer (with token)
Update account	`accountUpdate`	Customer (own profile)
Delete account	`accountDelete`	Customer (with token)
Admin create customer	`customerCreate`	Staff
Admin update customer	`customerUpdate`	Staff
Admin delete customer	`customerDelete`	Staff
Admin bulk delete	`customerBulkDelete`	Staff

Best Practices

Use accountRegister for self-service registration and customerCreate for staff-created accounts
Always configure redirectUrl for email confirmation and password reset to point to your storefront
Store custom customer data in metadata (public) or privateMetadata (staff-only)
Use permission groups to organize staff access -- avoid assigning permissions directly to users
Implement token refresh logic in your storefront to maintain sessions without re-authentication
Validate email confirmation befo

saleor-customers

How to add

Drop this on your repo README

Related skills

template-skill

slack-gif-creator

baoyu-compress-image

zzz-one-dragon-player

Get new Outros skills every Monday