Team API

REST API endpoints for managing team members and invitations.

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 instead.

List Team Members

GET /api/v1/team/members

Returns the store's team members with their user details and role. deactivatedAt is the time an owner or admin switched the member off, or null. A deactivated member stays on the team and keeps their role, but can't open the store, use the API through an app, or talk to the AI Assistant until they are reactivated in Settings → Team.

Query Parameters

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

Response

{
  "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",
      "deactivatedAt": null
    }
  ],
  "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.

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 – promoting to owner here is not allowed, and changing the current owner's role returns 409.

Request Body

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)

{
  "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",
  "deactivatedAt": null
}

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).

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)

{
  "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 or is deactivated.

Request Body

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)

{
  "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",
    "deactivatedAt": null
  }
}

List Invitations

GET /api/v1/team/invitations

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

Query Parameters

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

Response

{
  "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.

Every invitation is checked against the plan's staff accounts. The store owner does not use one; every other member does, and so does each pending invitation until it is accepted or cancelled. A deactivated member still uses theirs. Once they are all in use, the endpoint returns 403 with { "error": "Every staff account on your plan is taken. Upgrade your plan to invite more members." } – upgrade the plan to invite more people.

Request Body

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)

{
  "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"
}

Error Responses

Get Invitation

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

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

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.

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)

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