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/developer/users/overview 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 before allowing customers to place orders
- Use
channel parameter in registration to send channel-specific confirmation emails
- Handle
tokensDeactivateAll for security-sensitive operations like password changes
- Prefer
accountAddressCreate for customer-facing flows and addressCreate for admin flows
Fetch the Saleor authentication and user management documentation for exact mutation inputs, permission enums, and token handling patterns before implementing.
1---2name: saleor-customers-23description: Manage Saleor customers and staff — customer accounts, registration, addresses, staff users, permission groups, and authentication. Use when working with user management.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/saleor-customers-27---89# Saleor Customer and Staff Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io customers accounts registration` for customer account model and registration flow152. Web-search `site:docs.saleor.io staff users permissions groups` for staff management and permission system163. Web-search `site:docs.saleor.io authentication JWT tokens` for authentication flow and token handling174. Fetch `https://docs.saleor.io/developer/users/overview` and review User model, addresses, and account operations185. Web-search `site:docs.saleor.io permission groups MANAGE_PRODUCTS MANAGE_ORDERS` for the full list of available permissions1920## Customer Model2122Saleor uses a single `User` entity for both customers and staff. The `isStaff` flag distinguishes between them.2324| Field | Description |25|-------|-------------|26| `id` | Unique user identifier |27| `email` | Email address (unique, used for login) |28| `firstName` | Customer first name |29| `lastName` | Customer last name |30| `isActive` | Whether the account is enabled |31| `isStaff` | Whether the user has dashboard access |32| `dateJoined` | Account creation timestamp |33| `lastLogin` | Most recent login timestamp |34| `metadata` | Public key-value metadata |35| `privateMetadata` | Staff-only key-value metadata |36| `languageCode` | Preferred language |37| `defaultShippingAddress` | Default shipping address |38| `defaultBillingAddress` | Default billing address |3940## Customer Registration and Login4142### Registration Flow4344| Step | Mutation | Description |45|------|----------|-------------|46| 1. Register | `accountRegister` | Create account with email and password |47| 2. Confirm email | `confirmAccount` | Verify email with token from confirmation email |48| 3. Active account | -- | Account is active after confirmation |4950### Registration Input5152| Field | Required | Description |53|-------|----------|-------------|54| `email` | Yes | Customer email address |55| `password` | Yes | Account password |56| `firstName` | No | First name |57| `lastName` | No | Last name |58| `redirectUrl` | Yes | URL for email confirmation link |59| `channel` | Yes | Channel slug for channel-specific registration |60| `languageCode` | No | Preferred language for communications |61| `metadata` | No | Initial metadata key-value pairs |6263### Login Flow6465| Step | Mutation | Description |66|------|----------|-------------|67| 1. Obtain tokens | `tokenCreate` | Provide email + password; returns JWT access and refresh tokens |68| 2. Use access token | -- | Include in `Authorization: Bearer <token>` header |69| 3. Refresh token | `tokenRefresh` | Exchange refresh token for new access token |70| 4. Verify token | `tokenVerify` | Check if a token is still valid |7172## JWT Authentication Flow7374| Token Type | Lifetime | Purpose |75|------------|----------|---------|76| Access token | Short-lived (configurable, default ~5 min) | Authenticate API requests |77| Refresh token | Long-lived (configurable) | Obtain new access tokens |78| CSRF token | Per-session | Protect against cross-site request forgery |7980### Token Mutations8182| Operation | Mutation | Notes |83|-----------|----------|-------|84| Login | `tokenCreate` | Returns `token`, `refreshToken`, `csrfToken` |85| Refresh | `tokenRefresh` | Requires `refreshToken`; returns new `token` |86| Verify | `tokenVerify` | Returns `isValid` and decoded payload |87| Deactivate all | `tokensDeactivateAll` | Invalidate all tokens for the user |8889> **Fetch live docs** for token expiration configuration and any changes to the JWT authentication model.9091## Customer Addresses9293Each customer can store multiple addresses with defaults for shipping and billing:9495| Field | Description |96|-------|-------------|97| `firstName` | Address first name |98| `lastName` | Address last name |99| `companyName` | Optional company name |100| `streetAddress1` | Primary street address |101| `streetAddress2` | Additional address line |102| `city` | City name |103| `postalCode` | Postal or ZIP code |104| `country` | ISO 3166-1 alpha-2 country code |105| `countryArea` | State or province |106| `phone` | Phone number |107| `isDefaultShippingAddress` | Default for shipping |108| `isDefaultBillingAddress` | Default for billing |109110### Address Mutations111112| Operation | Mutation | Notes |113|-----------|----------|-------|114| Create address | `accountAddressCreate` | Customer self-service |115| Update address | `accountAddressUpdate` | Customer self-service |116| Delete address | `accountAddressDelete` | Customer self-service |117| Set default | `accountSetDefaultAddress` | Set shipping or billing default |118| Admin create | `addressCreate` | Staff creating address for a customer |119| Admin update | `addressUpdate` | Staff updating customer address |120| Admin delete | `addressDelete` | Staff deleting customer address |121122## Staff Users vs Customers123124| Aspect | Customer | Staff |125|--------|----------|-------|126| `isStaff` | `false` | `true` |127| Dashboard access | No | Yes |128| API scope | Storefront queries, own account | Admin queries, assigned permissions |129| Creation | `accountRegister` or `customerCreate` | `staffCreate` |130| Permissions | None (implicit storefront access) | Assigned via permission groups |131132### Staff Management Mutations133134| Operation | Mutation | Notes |135|-----------|----------|-------|136| Create staff | `staffCreate` | Set email, permissions, groups |137| Update staff | `staffUpdate` | Modify details and permissions |138| Delete staff | `staffDelete` | Remove staff user |139140## Permission Groups141142Permission groups bundle permissions and assign them to staff users:143144| Operation | Mutation |145|-----------|----------|146| Create group | `permissionGroupCreate` |147| Update group | `permissionGroupUpdate` |148| Delete group | `permissionGroupDelete` |149150### Key Permissions151152| Permission | Grants Access To |153|------------|-----------------|154| `MANAGE_PRODUCTS` | Products, categories, collections, product types |155| `MANAGE_ORDERS` | Orders, fulfillments, draft orders |156| `MANAGE_USERS` | Customer accounts and staff users |157| `MANAGE_STAFF` | Staff accounts and permission groups |158| `MANAGE_DISCOUNTS` | Vouchers and promotions |159| `MANAGE_SHIPPING` | Shipping zones and methods |160| `MANAGE_CHANNELS` | Channel configuration |161| `MANAGE_CHECKOUTS` | Checkout operations |162| `MANAGE_APPS` | App installation and configuration |163| `MANAGE_SETTINGS` | Site-wide settings |164| `MANAGE_TRANSLATIONS` | Content translations |165| `HANDLE_PAYMENTS` | Payment processing and transactions |166| `MANAGE_GIFT_CARD` | Gift card creation and management |167| `MANAGE_PAGE_TYPES_AND_ATTRIBUTES` | Page types and attributes |168169> **Fetch live docs** for the complete `PermissionEnum` -- additional permissions may exist for plugins and newer features.170171## Account Management Mutations172173| Operation | Mutation | Actor |174|-----------|----------|-------|175| Request password reset | `requestPasswordReset` | Customer |176| Set new password | `setPassword` | Customer (with token) |177| Change password | `passwordChange` | Customer (authenticated) |178| Request email change | `requestEmailChange` | Customer |179| Confirm email change | `confirmEmailChange` | Customer (with token) |180| Update account | `accountUpdate` | Customer (own profile) |181| Delete account | `accountDelete` | Customer (with token) |182| Admin create customer | `customerCreate` | Staff |183| Admin update customer | `customerUpdate` | Staff |184| Admin delete customer | `customerDelete` | Staff |185| Admin bulk delete | `customerBulkDelete` | Staff |186187## Best Practices188189- Use `accountRegister` for self-service registration and `customerCreate` for staff-created accounts190- Always configure `redirectUrl` for email confirmation and password reset to point to your storefront191- Store custom customer data in `metadata` (public) or `privateMetadata` (staff-only)192- Use permission groups to organize staff access -- avoid assigning permissions directly to users193- Implement token refresh logic in your storefront to maintain sessions without re-authentication194- Validate email confirmation before allowing customers to place orders195- Use `channel` parameter in registration to send channel-specific confirmation emails196- Handle `tokensDeactivateAll` for security-sensitive operations like password changes197- Prefer `accountAddressCreate` for customer-facing flows and `addressCreate` for admin flows198199Fetch the Saleor authentication and user management documentation for exact mutation inputs, permission enums, and token handling patterns before implementing.