Team Management

Invite team members, assign roles and locations, and manage permissions across your store.

Overview

The team API lets you invite people to your store, assign them roles that control what they can access, and optionally restrict them to specific locations. Every action a team member takes is tied to their identity for full audit trail visibility.

Invitations

Send email invites with a role pre-assigned. Invitees create an account or link an existing one.

Role-based access

Four built-in roles — owner, admin, member, viewer — with granular permission boundaries.

Location scoping

Assign team members to specific locations so they only see relevant inventory and orders.

Audit trail

Every create, update, and delete is attributed to the team member who performed it.

Invite a Member

Send an invitation by email with a pre-assigned role. The invitee receives a link to join the store. Pending invitations can be listed or revoked at any time.

const whale = new WhaleClient("wk_live_...");

// Invite a new team member
const invite = await whale.teamInvites.create({
  email: "sarah@example.com",
  role: "member",
  message: "Welcome to the team! You'll have access to products, orders, and customers."
});

// Response
{
  "object": "team_invite",
  "id": "inv_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "sarah@example.com",
  "role": "member",
  "status": "pending",
  "expires_at": "2026-03-17T08:00:00.000Z",
  "created_at": "2026-03-10T08:00:00.000Z"
}

Roles

Each team member is assigned one of four roles. Roles determine which areas of the store they can access and what actions they can perform.

Role	products	orders	customers	analytics	team	billing	api
owner	yes	yes	yes	yes	yes	yes	yes
admin	yes	yes	yes	yes	yes	--	yes
member	yes	yes	yes	--	--	--	--
viewer	--	--	--	yes	--	--	--

owner has full access including billing and account deletion. Only one owner per store. viewer has read-only access to analytics dashboards.

Location Assignment

Assign team members to specific store locations. When assigned, a member only sees inventory, orders, and activity for their assigned locations. Members without a location assignment have access to all locations by default.

// Assign a team member to a location
await whale.teamLocations.create({
  team_member_id: "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  location_id: "loc_store_downtown"
});

// Assign to a second location
await whale.teamLocations.create({
  team_member_id: "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012",
  location_id: "loc_warehouse_east"
});

// List a member's location assignments
const assignments = await whale.teamLocations.list({
  team_member_id: "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012"
});

// Response
{
  "object": "list",
  "data": [
    {
      "id": "tl_c3d4e5f6-a7b8-9012-cdef-345678901234",
      "team_member_id": "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "location_id": "loc_store_downtown",
      "location_name": "Downtown Store",
      "assigned_at": "2026-03-10T09:00:00.000Z"
    },
    {
      "id": "tl_d4e5f6a7-b8c9-0123-defg-456789012345",
      "team_member_id": "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "location_id": "loc_warehouse_east",
      "location_name": "East Warehouse",
      "assigned_at": "2026-03-10T09:05:00.000Z"
    }
  ]
}

List Team

Retrieve the current team roster with each member's role, email, and status. Filter by role or location to narrow results.

// List all team members
const team = await whale.teamMembers.list();

// Response
{
  "object": "list",
  "data": [
    {
      "id": "tm_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@example.com",
      "name": "Alex Chen",
      "role": "owner",
      "status": "active",
      "locations": [],
      "last_active_at": "2026-03-10T12:00:00.000Z",
      "joined_at": "2025-06-15T08:00:00.000Z"
    },
    {
      "id": "tm_b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "email": "sarah@example.com",
      "name": "Sarah Kim",
      "role": "member",
      "status": "active",
      "locations": ["loc_store_downtown", "loc_warehouse_east"],
      "last_active_at": "2026-03-10T11:45:00.000Z",
      "joined_at": "2026-03-10T10:00:00.000Z"
    },
    {
      "id": "tm_c3d4e5f6-a7b8-9012-cdef-345678901234",
      "email": "james@example.com",
      "name": "James Park",
      "role": "viewer",
      "status": "active",
      "locations": [],
      "last_active_at": "2026-03-09T16:30:00.000Z",
      "joined_at": "2026-01-20T08:00:00.000Z"
    }
  ]
}

API Reference

Method	Path	Description
GET	/v1/stores/{store_id}/team-members	List team members. Filter by role or location_id.
GET	/v1/stores/{store_id}/team-members/{id}	Get a single team member with role and location assignments.
PATCH	/v1/stores/{store_id}/team-members/{id}	Update a team member's role or metadata.
DELETE	/v1/stores/{store_id}/team-members/{id}	Remove a team member from the store.
GET	/v1/stores/{store_id}/team-invites	List pending invitations.
POST	/v1/stores/{store_id}/team-invites	Send a new team invitation.
DELETE	/v1/stores/{store_id}/team-invites/{id}	Revoke a pending invitation.
GET	/v1/stores/{store_id}/team-locations	List team-to-location assignments.
POST	/v1/stores/{store_id}/team-locations	Assign a team member to a location.
DELETE	/v1/stores/{store_id}/team-locations/{id}	Remove a team member from a location.