Team and roles

API REFERENCE

Team and roles

Members hold roles. Owner, admin, member and viewer are built in, and custom roles are composed from the permission catalog. The same permissions gate API routes and dashboard actions.

Roles

MethodPathPurposePermission
GET/merchants/:merchantId/roles/catalogPermission definitions and system roles.roles:read
GET/merchants/:merchantId/rolesSystem and custom roles with member counts.roles:read
POST/merchants/:merchantId/rolesCreate a custom role from permission keys.roles:write
GET/merchants/:merchantId/roles/:roleIdRead one role.roles:read
PATCH/merchants/:merchantId/roles/:roleIdUpdate name, description, permissions or active state.roles:write
DELETE/merchants/:merchantId/roles/:roleIdDelete a role that is not assigned to active members.roles:write
FieldTypeRequiredNotes
keystringNoPattern ^[a-z0-9][a-z0-9_-]*$; derived from the name when omitted.
namestringYes—
descriptionstringNo—
permissionsstring[]YesValidated against the permission catalog.

Members and invitations

MethodPathPurposePermission
GET/merchants/:merchantId/team/membersMembers with role, resolved permissions and profile fields.team:read
PATCH/merchants/:merchantId/team/members/:userIdChange a member's role.team:write
DELETE/merchants/:merchantId/team/members/:userIdMark a membership inactive.team:write
GET/merchants/:merchantId/team/invitationsPending and past invitations.team:read
POST/merchants/:merchantId/team/invitationsInvite an email with a role and a seven-day expiry.team:write
DELETE/merchants/:merchantId/team/invitations/:invitationIdRevoke an invitation.team:write
POST/merchants/:merchantId/team/transfer-ownershipPromote a member to owner and demote the current owner.team:transfer
POST/invitations/:token/acceptAccept an invitation as the signed-in user.—

Owners cannot be removed through the members route, and callers cannot remove themselves. Ownership moves only through the transfer route, which updates both memberships in one transaction.

Permission catalog

products:read|writeplans:read|writeprices:read|writeaddons:read|writecoupons:read|writecustomers:read|writesubscriptions:read|writeinvoices:read|writepayments:read|writerefunds:read|writegateways:read|writetax:read|writeusage:read|writeanalytics:readwebhooks:read|writeapikeys:read|writeteam:read|write|transferroles:read|writesettings:read|writebilling:read|write

Conflicts

Creating a role with an existing key or a system role key returns 409. Inviting an existing member, or an email with a live invitation, also returns 409. Deleting a role that is still assigned to active members returns 409.