Manage who has access to your store. List and update team members, invite new people by email, and transfer store ownership. Roles are `owner`, `admin`, and `member` – the owner cannot be removed or demoted directly; use [Transfer Ownership](#transfer-ownership) instead.

## List Team Members

```
GET /api/v1/team/members
```

Returns the store's team members with their user details and role.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Members per page (1-100) |
| `offset` | `number` | 0 | Members to skip |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/members
```

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "userId": "0191abc0-0000-7000-8000-000000000010",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "role": "owner",
      "createdAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Get Team Member

```
GET /api/v1/team/members/:id
```

Returns a single team member by member ID. Returns `404` if the member is not in this store.

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/members/0191abc0-1234-7def-8000-000000000001
```

---

## Update Team Member

```
PATCH /api/v1/team/members/:id
```

Changes a member's role to `admin` or `member`. To make someone the owner, use [Transfer Ownership](#transfer-ownership) – promoting to `owner` here is not allowed, and changing the current owner's role returns `409`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `role` | `"admin" \| "member"` | Yes | New role for the member |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' \
  https://your-store.yns.store/api/v1/team/members/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "userId": "0191abc0-0000-7000-8000-000000000010",
  "name": "Jane Doe",
  "email": "jane@acme.com",
  "role": "admin",
  "createdAt": "2024-06-15T10:30:00.000Z"
}
```

---

## Delete Team Member

```
DELETE /api/v1/team/members/:id
```

Removes a member from the store. The owner cannot be removed – transfer ownership first (returns `409`).

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/members/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```

---

## Transfer Ownership

```
POST /api/v1/team/transfer-ownership
```

Promotes the given member to `owner` and demotes the current owner to `admin`, atomically. Billing and Stripe are untouched. Returns `409` if the target member is already the owner.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `memberId` | `string` | Yes | ID of the member to promote to owner |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"memberId": "0191abc0-1234-7def-8000-000000000002"}' \
  https://your-store.yns.store/api/v1/team/transfer-ownership
```

### Response (200)

```json
{
  "owner": {
    "id": "0191abc0-1234-7def-8000-000000000002",
    "userId": "0191abc0-0000-7000-8000-000000000011",
    "name": "John Smith",
    "email": "john@acme.com",
    "role": "owner",
    "createdAt": "2024-06-16T09:00:00.000Z"
  }
}
```

---

## List Invitations

```
GET /api/v1/team/invitations
```

Returns the store's invitations, both pending and resolved.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Invitations per page (1-100) |
| `offset` | `number` | 0 | Invitations to skip |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/invitations
```

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000003",
      "email": "newhire@acme.com",
      "role": "member",
      "status": "pending",
      "expiresAt": "2024-06-22T10:30:00.000Z",
      "createdAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Create Invitation

```
POST /api/v1/team/invitations
```

Invites someone to the store by email. Sends the same invitation email the dashboard does; the invitee becomes a member once they accept. Returns `409` if the email is already a member or already has a pending invitation.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | `string` | Yes | Email address to invite |
| `role` | `"admin" \| "member"` | No | Role the invitee will have once they accept (default: `member`) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "newhire@acme.com", "role": "member"}' \
  https://your-store.yns.store/api/v1/team/invitations
```

### Response (201)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000003",
  "email": "newhire@acme.com",
  "role": "member",
  "status": "pending",
  "expiresAt": "2024-06-22T10:30:00.000Z",
  "createdAt": "2024-06-15T10:30:00.000Z"
}
```

---

## Get Invitation

```
GET /api/v1/team/invitations/:id
```

Returns a single invitation by ID. Returns `404` if it does not exist.

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/invitations/0191abc0-1234-7def-8000-000000000003
```

---

## Delete Invitation

```
DELETE /api/v1/team/invitations/:id
```

Revokes a pending invitation. Returns `404` if it does not exist.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/team/invitations/0191abc0-1234-7def-8000-000000000003
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```