Cowdidocs
API ReferenceMerchants

Create a merchant

POST
/v1/organizations/{organizationId}/merchants

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.

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

Path Parameters

organizationId*string

Unique identifier (slug) of the organization.

Request Body

application/json

Request to create a merchant under the organization.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/organizations/greenwheels/merchants" \  -H "Content-Type: application/json" \  -d '{    "id": "550e8400-e29b-41d4-a716-446655440001",    "name": "Jane\'s Motors"  }'
{  "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"}
{  "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"}
{  "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": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List merchants GET

List every merchant under the organization. Requires the caller's `org:merchants:read` permission on the organization. Returns every match; the response is not paginated.

List the caller's merchants GET

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.