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
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/roles/catalog | Permission definitions and system roles. | roles:read |
| GET | /merchants/:merchantId/roles | System and custom roles with member counts. | roles:read |
| POST | /merchants/:merchantId/roles | Create a custom role from permission keys. | roles:write |
| GET | /merchants/:merchantId/roles/:roleId | Read one role. | roles:read |
| PATCH | /merchants/:merchantId/roles/:roleId | Update name, description, permissions or active state. | roles:write |
| DELETE | /merchants/:merchantId/roles/:roleId | Delete a role that is not assigned to active members. | roles:write |
| Field | Type | Required | Notes |
|---|---|---|---|
| key | string | No | Pattern ^[a-z0-9][a-z0-9_-]*$; derived from the name when omitted. |
| name | string | Yes | — |
| description | string | No | — |
| permissions | string[] | Yes | Validated against the permission catalog. |
Members and invitations
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/team/members | Members with role, resolved permissions and profile fields. | team:read |
| PATCH | /merchants/:merchantId/team/members/:userId | Change a member's role. | team:write |
| DELETE | /merchants/:merchantId/team/members/:userId | Mark a membership inactive. | team:write |
| GET | /merchants/:merchantId/team/invitations | Pending and past invitations. | team:read |
| POST | /merchants/:merchantId/team/invitations | Invite an email with a role and a seven-day expiry. | team:write |
| DELETE | /merchants/:merchantId/team/invitations/:invitationId | Revoke an invitation. | team:write |
| POST | /merchants/:merchantId/team/transfer-ownership | Promote a member to owner and demote the current owner. | team:transfer |
| POST | /invitations/:token/accept | Accept 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|writeConflicts
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.