Cowdidocs
API ReferenceMerchants

List the caller's merchants

GET
/v1/user/merchants

List the merchants the caller is an active member of, within the caller's organization. Requires an authenticated user token. Returns every match; the response is not paginated.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/user/merchants"
[  {    "id": "550e8400-e29b-41d4-a716-446655440001",    "organization_id": "greenwheels",    "name": "Jane's Motors",    "contact_email": "jane@example.com",    "contact_phone_number": "+254712345678",    "status": "PENDING",    "created_at": "2026-03-15T10:00:00Z",    "updated_at": "2026-03-20T08:30:00Z",    "resource_id": "string"  }]
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Create a merchant POST

Create a merchant under the organization, using the merchant's ID in the sales app as `id`. Requires the caller's `org:merchants:write` permission on the organization. Idempotent on `id`: returns 200 with the existing merchant when one already has this ID, and 404 when a different organization already used this ID. Otherwise creates the merchant with `PENDING` status and returns 201.

Get merchant access GET

Inspect one user's direct, group, and inherited assignments with provider-evaluated effective permissions. Requires `org:merchants:read`. The `user_id` filter is required. The response contains at most one person and has no pagination links. Organization members remain visible with no merchant roles.