Seller & Store API

Catalog: /apis/seller-api

Manages seller storefront registration, logo and banner multimedia paths, geographical location settings, following status tracking, and seller payouts.

Endpoints Reference

Complete list of GraphQL mutations, queries, gRPC procedures, and HTTP routes for this module.

GraphQL Query

myStore

Returns the storefront metadata belonging to the authenticated seller session.

🔒 JWT Auth SELLER

Request Syntax / Parameters

query { myStore { id storeName storeSlug status isVerified rating } }

Expected JSON Response

{ "data": { "myStore": { "id": "117f5472-ac34-44ab-8e5d-9687dfdfc443", "storeName": "Harare CBD Premium Store", "storeSlug": "harare-cbd-premium-store", "status": "VERIFIED", "isVerified": true, "rating": 4.8 } } }

GraphQL Mutation

createStore(input: CreateStoreInput!)

Registers a storefront profile, listing description, and geographical coordinates (essential for nearby products searches). Sets status to PENDING.

🔒 JWT Auth SELLER

Request Syntax / Parameters

mutation { createStore(input: { storeName: "Harare CBD Premium Store", description: "Electronics CBD", latitude: -17.8292, longitude: 31.0522 }) { id status } }

Expected JSON Response

{ "data": { "createStore": { "id": "117f5472-ac34-44ab-8e5d-9687dfdfc443", "status": "PENDING" } } }

GraphQL Mutation

updateSellerStatus(sellerId: ID!, status: SellerStatus!)

Promotes, suspends, or verifies a storefront profile. Restated for admins only.

🔒 JWT Auth ADMIN

Request Syntax / Parameters

mutation { updateSellerStatus(sellerId: "117f5472-ac34-44ab-8e5d-9687dfdfc443", status: VERIFIED) { id isVerified status } }

Expected JSON Response

{ "data": { "updateSellerStatus": { "id": "117f5472-ac34-44ab-8e5d-9687dfdfc443", "isVerified": true, "status": "VERIFIED" } } }

GraphQL Mutation

followStore(sellerId: ID!)

Registers a buyer follow connection to receive alerts when products are published.

🔒 JWT Auth BUYER

Request Syntax / Parameters

mutation { followStore(sellerId: "117f5472-ac34-44ab-8e5d-9687dfdfc443") }

Expected JSON Response

{ "data": { "followStore": true } }

Database Tables & Data Models

Relational database schemas and custom payload models governing this service domain.

📂 sellers (PostgreSQL)

Contains storefront settings, geolocation points, and status ratings.

Field Name	Data Type	Description / Constraint
id	UUID (Primary Key)	Unique storefront identifier.
user_id	UUID	Associated owner user identifier.
store_name	VARCHAR(255)	Display name of storefront.
store_slug	VARCHAR(255)	URL-friendly store slug (unique).
latitude / longitude	DOUBLE PRECISION	Geographical coordinates for local search filters.
status	VARCHAR(30)	Onboarding state: 'PENDING' \| 'PROCESSING' \| 'VERIFIED' \| 'SUSPENDED'.

📂 store_follows (PostgreSQL)

Junction map tracking which buyers follow which storefronts.

Field Name	Data Type	Description / Constraint
user_id	UUID	Follower buyer identifier.
seller_id	UUID	Target storefront seller identifier.
created_at	TIMESTAMPTZ	Timestamp when following began.