Teams & Invitations
Manage organizations, team members, roles, and invitations in ShopySeed.
Teams & Invitations
ShopySeed is built around multi-tenant organizations. Each user can belong to multiple organizations, and each organization has its own members, roles, and subscription.
Organizations
Creating an Organization
Organizations are created during the onboarding flow (/onboarding) after a user's first login. Each organization gets:
- A unique name and slug
- A dedicated database schema for tenant isolation
- A default Free plan subscription
- The creator assigned as Owner
Switching Organizations
Users with multiple organizations can switch between them via the organization selector in the dashboard sidebar. The current organization context is stored in OrgContext and sent as X-Organization-Id header on API requests.
Roles
ShopySeed implements 4 roles with hierarchical permissions:
| Role | Invite Members | Manage Members | Billing | Delete Org |
|---|---|---|---|---|
| Owner | ✅ | ✅ | ✅ | ✅ |
| Admin | ✅ | ✅ | ✅ | ❌ |
| Member | ❌ | ❌ | ❌ | ❌ |
| Viewer | ❌ | ❌ | ❌ | ❌ |
Roles are enforced both on the backend (via RolesGuard) and frontend (UI conditionals).
Team Invitations
Inviting a Member
- Owner or Admin clicks "Invite Member" on the Team page (
/dashboard/team) - Enters the invitee's email and selects a role
- Backend creates an
OrganizationInvitationwith a unique token - An invitation email is sent with a link to accept
Invitation Details
- Expiry: 7 days
- Duplicate check: Cannot send two pending invitations to the same email
- Existing user check: If the email is already a member, a
409 Conflictis returned
Accepting an Invitation
- Invitee clicks the link →
/auth/accept-invite/[token] - If not logged in, redirected to register/login first
- Backend validates the token, checks email match, and creates the membership
- Invitation is marked as accepted
Plan Limits
Invitations respect the organization's plan member limit:
- Free: 3 members max
- Pro: 10 members max
- Enterprise: Unlimited
If the organization is at or over its limit (e.g., after a downgrade), new invitations are blocked. Existing members are not removed — they just can't add more until they upgrade or reduce team size.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /organizations | List user's organizations |
POST | /organizations | Create a new organization |
GET | /organizations/:id | Get organization details |
PATCH | /organizations/:id | Update organization |
DELETE | /organizations/:id | Delete organization (Owner only) |
GET | /organizations/:id/members | List members |
POST | /organizations/:id/invite | Invite a member by email |
POST | /organizations/accept-invite/:token | Accept an invitation |
PATCH | /organizations/:id/members/:userId/role | Change member role |
DELETE | /organizations/:id/members/:userId | Remove a member |
Over-Limit Handling
When an organization has more members than their plan allows (typically after a downgrade):
- A warning banner appears on the Team page explaining the situation
- The Invite button is disabled
- A link to upgrade is provided
- Existing members continue to work normally — no one is locked out