Getting Started
Vendeey Public API
Integrate your Vendeey store into your own website or application. Access products, categories, orders, payments, reviews, and more through our RESTful API.
Quick Start
Get up and running in minutes
API Reference
Complete endpoint documentation
Code Examples
Ready-to-use code snippets
ProMax Plan Required
The Public API is available exclusively for ProMax plan subscribers.
Quick Start
Follow these three steps to start using the Vendeey API.
1
Subscribe to ProMax
The API is available exclusively for ProMax plan subscribers.
2
Generate Your API Key
Go to Settings > Developer and generate your unique API key.
3
Register Allowed Origins
For security, register the domains that will make API requests (e.g., https://yoursite.com).
Authentication
All API requests require authentication using an API key passed in the request headers.
Required Headers
json
{"x-api-key": "vnd_your_api_key_here","Content-Type": "application/json"}
Example Request
bash
curl -X GET 'https://api.vendeey.com/api/public/store/info' \-H 'x-api-key: vnd_your_api_key_here' \-H 'Content-Type: application/json'
Security Best Practices
- Never expose your API key in client-side code. Use environment variables or a backend proxy.
- Register all domains that will make API requests to prevent unauthorized access.
- Regenerate your API key immediately if you suspect it has been compromised.
User Registration
Endpoints for registering new user accounts. Registration creates a new user with the 'user' role and sends a verification email.
POST
/auth/registerRegister a new user account. Returns an access token and user data. A verification email is sent automatically.
Request Body
json
{"email": "user@example.com","firstName": "John","lastName": "Doe","password": "SecurePass123!","phoneNumber": "+234 800 123 4567"}
Response
json
{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user": {"id": "usr_abc123xyz","email": "user@example.com","firstName": "John","lastName": "Doe","role": "user","isEmailVerified": false,"mustChangePassword": false}}
POST
/auth/check-contactCheck if an email or phone number is available for registration before submitting the form.
Request Body
json
{"email": "user@example.com","phone": "+234 800 123 4567"}
Response
json
{"available": true,"message": "Email and phone are available"}// If not available:{"available": false,"message": "Email already registered"}
User Login
Endpoints for authenticating users. Supports login with email or phone number. Returns JWT access token stored in httpOnly cookie for security.
POST
/auth/loginAuthenticate a user with email/phone and password. Returns access token and user data. Token is also set in httpOnly cookie.
Request Body
json
{"emailOrPhone": "user@example.com","password": "SecurePass123!"}
Response
json
{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user": {"id": "usr_abc123xyz","email": "user@example.com","firstName": "John","lastName": "Doe","role": "user","isEmailVerified": true,"mustChangePassword": false}}// For vendors:{"accessToken": "...","user": {"id": "usr_abc123xyz","email": "vendor@example.com","firstName": "Jane","lastName": "Smith","role": "vendor","isEmailVerified": true,"vendorId": "vnd_xyz789"}}// For staff:{"accessToken": "...","user": {"id": "usr_abc123xyz","email": "staff@example.com","firstName": "Bob","lastName": "Wilson","role": "staff","vendorId": "vnd_xyz789","staffId": "stf_abc123","permissions": ["products:view", "orders:view", "orders:manage"]}}
POST
/auth/logoutLog out the current user by clearing the auth cookie.
Response
json
{"success": true,"message": "Logged out successfully"}
GET
/auth/profileGet the current authenticated user's profile. Requires valid JWT token.
Response
json
{"id": "usr_abc123xyz","email": "user@example.com","firstName": "John","lastName": "Doe","phoneNumber": "+234 800 123 4567","role": "user","isActive": true,"isEmailVerified": true,"createdAt": "2024-01-15T10:30:00Z","updatedAt": "2024-01-15T10:30:00Z"}
POST
/auth/generate-tokenGenerate a one-time login token for passwordless authentication. Token expires in 15 minutes.
Request Body
json
{"email": "user@example.com","redirectUrl": "https://yoursite.com/dashboard"}
Response
json
{"token": "ott_abc123xyz789","expiresAt": "2024-01-15T12:15:00Z","loginUrl": "https://vendeey.com/signin?token=ott_abc123xyz789"}
POST
/auth/login-with-tokenLogin using a one-time token received via email or generated programmatically.
Request Body
json
{"token": "ott_abc123xyz789"}
Response
json
{"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user": {"id": "usr_abc123xyz","email": "user@example.com","firstName": "John","lastName": "Doe","role": "user","isEmailVerified": true},"redirectUrl": "https://yoursite.com/dashboard"}
Password Management
Endpoints for password reset and change functionality. Password must be at least 8 characters with uppercase, lowercase, number, and special character.
POST
/auth/forgot-passwordRequest a password reset email. Returns the same response whether email exists or not for security.
Request Body
json
{"email": "user@example.com"}
Response
json
{"success": true,"message": "Password reset instructions sent to your email"}
POST
/auth/reset-passwordReset password using the token received via email. Token expires after 1 hour.
Request Body
json
{"token": "rst_abc123xyz789","newPassword": "NewSecurePass456!"}
Response
json
{"success": true,"message": "Password reset successful"}
POST
/auth/change-passwordChange password for authenticated user. Requires current password for verification.
Request Body
json
{"currentPassword": "OldPass123!","newPassword": "NewSecurePass456!"}
Response
json
{"success": true,"message": "Password changed successfully"}
POST
/auth/change-mandatory-passwordChange mandatory password for newly approved vendors. Required when mustChangePassword is true.
Request Body
json
{"newPassword": "NewSecurePass456!","confirmPassword": "NewSecurePass456!"}
Response
json
{"success": true,"message": "Password changed successfully","accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user": {"id": "usr_abc123xyz","email": "vendor@example.com","role": "vendor","mustChangePassword": false}}
Email Verification
Endpoints for verifying user email addresses. Verification tokens expire after 24 hours.
GET
/auth/verify-email/:tokenVerify email address using the token sent via email.
Response
json
{"success": true,"message": "Email verified successfully","user": {"id": "usr_abc123xyz","email": "user@example.com","isEmailVerified": true}}
POST
/auth/resend-verificationResend email verification to the authenticated user. Rate limited to once per 60 seconds.
Response
json
{"success": true,"message": "Verification email sent"}// If rate limited:{"success": false,"message": "Please wait 60 seconds before requesting another verification email"}
Store Information
Endpoints for retrieving store details, branding, and configuration.
GET
/api/public/store/infoGet lightweight store information including name, description, branding, and contact details.
Response
json
{"businessName": "My Store","storeSlug": "my-store","businessDescription": "Your one-stop shop for quality products","storeLogo": "https://storage.example.com/logo.png","coverImage": "https://storage.example.com/cover.png","primaryColor": "#000000","contactEmail": "hello@mystore.com","contactPhone": "+234 800 123 4567"}
GET
/api/public/store/countsGet total product and category counts for the store.
Response
json
{"productCount": 150,"categoryCount": 12}
GET
/api/public/store/subscriptionGet the store's subscription status and plan details.
Response
json
{"data": {"plan": "promax","status": "active","expiresAt": "2025-12-31T23:59:59Z"}}
Products
Endpoints for listing, searching, and retrieving product details.
GET
/api/public/store/products?page=1&limit=20&categoryId=xxx&featured=trueGet paginated list of products with optional filtering.
Response
json
{"products": [{"id": "prod_abc123","name": "Premium Sneakers","price": 45000,"compareAtPrice": 55000,"images": ["https://..."],"category": { "id": "cat_123", "name": "Footwear" },"inStock": true,"variants": [...]}],"pagination": {"page": 1,"limit": 20,"total": 150,"hasMore": true}}
GET
/api/public/store/products/featured?limit=8Get featured products for homepage display.
Response
json
{"products": [{"id": "prod_abc123","name": "Premium Sneakers","price": 45000,"images": ["https://..."],"featured": true}]}
GET
/api/public/store/products/:productIdGet detailed information about a single product including all variants and images.
Response
json
{"id": "prod_abc123","name": "Premium Sneakers","price": 45000,"compareAtPrice": 55000,"description": "High-quality premium sneakers...","images": ["https://storage.example.com/img1.jpg","https://storage.example.com/img2.jpg"],"variants": [{"id": "var_123","name": "Size 42","price": 45000,"stock": 10,"sku": "SNK-42"}],"category": { "id": "cat_123", "name": "Footwear" },"inStock": true,"createdAt": "2024-01-15T10:30:00Z"}
Categories
Endpoints for retrieving product categories and their products.
GET
/api/public/store/categoriesGet all product categories with product counts.
Response
json
{"categories": [{"id": "cat_abc123","name": "Electronics","slug": "electronics","image": "https://...","productCount": 25},{"id": "cat_def456","name": "Fashion","slug": "fashion","productCount": 48}]}
GET
/api/public/store/categories/:categoryId/productsGet all products within a specific category.
Response
json
{"category": {"id": "cat_abc123","name": "Electronics","slug": "electronics"},"products": [{"id": "prod_123","name": "Wireless Headphones","price": 25000,"images": ["https://..."]}],"pagination": {"total": 25,"page": 1,"hasMore": true}}
Collections
Endpoints for retrieving curated product collections.
GET
/api/public/store/collectionsGet all collections with their products.
Response
json
{"collections": [{"id": "col_abc123","name": "Summer Sale","description": "Hot deals for the summer season","image": "https://...","products": [{ "id": "prod_123", "name": "Beach Hat", "price": 5000 }]}]}
GET
/api/public/store/collections/summaryGet lightweight collection summary without full product details.
Response
json
{"collections": [{"id": "col_abc123","name": "Summer Sale","productCount": 15},{"id": "col_def456","name": "New Arrivals","productCount": 8}]}
Services
Endpoints for service-based businesses offering bookable services.
GET
/api/public/store/servicesGet all available services with pricing and duration.
Response
json
{"services": [{"id": "svc_abc123","name": "Hair Styling","description": "Professional hair styling service","price": 15000,"duration": 60,"image": "https://..."},{"id": "svc_def456","name": "Consultation","description": "One-on-one consultation session","price": 10000,"duration": 30}]}
Search
Endpoints for searching products and categories.
GET
/api/public/store/search?q=sneakers&limit=10&offset=0Search products and categories by keyword.
Response
json
{"products": [{"id": "prod_abc123","name": "Premium Sneakers","price": 45000,"images": ["https://..."]}],"categories": [{"id": "cat_123","name": "Footwear"}],"total": 25}
Stock Management
Endpoints for managing stock reservations during checkout.
POST
/api/public/store/stock/reserveCreate stock reservations for items during checkout. Reservations expire after 15 minutes.
Request Body
json
{"paymentReference": "ref_abc123xyz","items": [{"productId": "prod_abc123","quantity": 2,"productName": "Premium Sneakers","productPrice": 45000,"variantId": "var_123"}],"paymentMethod": "card","customerEmail": "customer@example.com"}
Response
json
{"success": true,"data": {"reservations": [{"id": "res_123","productId": "prod_abc123","quantity": 2,"status": "reserved"}],"expiresAt": "2024-01-15T12:15:00Z","timeRemaining": 900}}
POST
/api/public/store/stock/cancel/:paymentReferenceCancel stock reservations when customer abandons checkout.
Response
json
{"success": true,"message": "Reservations cancelled successfully"}
GET
/api/public/store/stock/status/:paymentReferenceCheck the current status of stock reservations.
Response
json
{"success": true,"data": {"isActive": true,"expiresAt": "2024-01-15T12:15:00Z","timeRemaining": 600,"items": [{"productId": "prod_abc123","quantity": 2,"reserved": true}]}}
Orders
Endpoints for creating and managing orders.
POST
/api/public/store/ordersSubmit a new order. Supports multipart/form-data for bank transfer receipt uploads.
Request Body
json
{"customerName": "John Doe","customerEmail": "john@example.com","customerPhone": "+234 800 123 4567","paymentMethod": "card","paymentReference": "ref_abc123xyz","deliveryMethod": "delivery","shippingAddress": "123 Main Street, Lagos","shippingState": "Lagos","items": [{"productId": "prod_abc123","productName": "Premium Sneakers","quantity": 2,"unitPrice": 45000,"variantId": "var_123","variantName": "Size 42"}],"subtotal": 90000,"shippingCost": 2500,"tax": 0,"discount": 0,"couponCode": "SAVE10"}
Response
json
{"success": true,"data": {"orderId": "ord_abc123xyz","orderNumber": "ORD-2024-001","status": "pending","totalAmount": 92500},"message": "Order submitted successfully"}
Payments
Endpoints for initializing and verifying payments.
POST
/api/public/payments/initializeInitialize a card payment. Returns a Paystack authorization URL where the customer completes payment.
Request Body
json
{"amount": 92500,"customerEmail": "customer@example.com","customerName": "John Doe","customerPhone": "+234 800 123 4567","orderId": "ord_abc123","description": "Order payment","successUrl": "https://yoursite.com/payment/success","cancelUrl": "https://yoursite.com/payment/cancel","metadata": {"orderId": "ord_abc123","source": "custom_website"}}
Response
json
{"success": true,"message": "Payment initialized successfully","data": {"reference": "PAY_abc123xyz789","authorizationUrl": "https://checkout.paystack.com/xxx","accessCode": "xxx123","amount": 92500,"currency": "NGN"}}
GET
/api/public/payments/verify/:referenceVerify the status of a payment transaction after customer completes payment.
Response
json
{"success": true,"message": "Payment verified successfully","data": {"status": "success","amount": 92500,"currency": "NGN","reference": "PAY_abc123xyz789","channel": "card","paidAt": "2024-01-15T10:35:00Z"}}
GET
/api/public/payments/status/:referenceQuick check of payment status without full verification.
Response
json
{"success": true,"data": {"reference": "PAY_abc123xyz789","status": "success","amount": 92500,"paidAt": "2024-01-15T10:35:00Z"}}
Bookings
Endpoints for creating service bookings.
POST
/api/public/bookingsCreate a new service booking.
Request Body
json
{"serviceId": "svc_abc123","fullName": "John Doe","email": "john@example.com","phone": "+234 800 123 4567","bookingDate": "2024-01-20","bookingTime": "10:00","duration": 60,"notes": "First time customer","serviceName": "Hair Styling","basePrice": 15000,"totalAmount": 15000,"currency": "NGN"}
Response
json
{"success": true,"message": "Booking created successfully","data": {"id": "bkg_abc123xyz","status": "pending","bookingDate": "2024-01-20","bookingTime": "10:00","confirmationCode": "BKG-001"}}
Product Reviews
Endpoints for managing product reviews and ratings.
GET
/api/public/products/:productId/reviews?page=1&limit=10&minRating=4Get reviews for a specific product.
Response
json
{"reviews": [{"id": "rev_abc123","rating": 5,"title": "Excellent product!","review": "This product exceeded my expectations...","author": "John D.","verified": true,"helpfulCount": 12,"createdAt": "2024-01-10T15:30:00Z"}],"pagination": {"page": 1,"total": 48,"hasMore": true}}
GET
/api/public/products/:productId/reviews/summaryGet rating summary and distribution for a product.
Response
json
{"averageRating": 4.5,"totalReviews": 128,"distribution": {"5": 80,"4": 30,"3": 10,"2": 5,"1": 3}}
POST
/api/public/products/:productId/reviewsSubmit a new product review.
Request Body
json
{"rating": 5,"title": "Amazing quality!","review": "This product is exactly what I was looking for...","userId": "user_abc123"}
Response
json
{"success": true,"message": "Review submitted successfully","data": {"id": "rev_xyz789","status": "pending_approval"}}
POST
/api/public/products/reviews/:reviewId/helpfulMark a review as helpful.
Response
json
{"success": true,"message": "Review marked as helpful","data": {"helpfulCount": 13}}
Product Questions
Endpoints for product Q&A.
GET
/api/public/products/:productId/questionsGet questions and answers for a product.
Response
json
{"success": true,"data": [{"id": "q_abc123","question": "Does this come in other colors?","answer": "Yes, we have black, white, and red options available.","status": "answered","askedBy": "Jane D.","createdAt": "2024-01-08T12:00:00Z","answeredAt": "2024-01-08T14:30:00Z"}]}
POST
/api/public/products/:productId/questionsSubmit a question about a product.
Request Body
json
{"question": "Is this available in size XL?","userId": "user_abc123"}
Response
json
{"success": true,"message": "Question submitted successfully","data": {"id": "q_xyz789","status": "pending"}}
Coupons
Endpoints for retrieving available discount coupons.
GET
/api/public/store/couponsGet all active coupons for the store.
Response
json
{"success": true,"data": [{"id": "cpn_abc123","code": "SAVE10","type": "percentage","value": 10,"minOrderAmount": 10000,"maxDiscount": 5000,"validUntil": "2024-03-31T23:59:59Z","usageLimit": 100,"usageCount": 45},{"id": "cpn_def456","code": "FLAT500","type": "fixed","value": 500,"minOrderAmount": 5000}]}
Delivery
Endpoints for calculating delivery costs.
POST
/api/public/store/delivery/costCalculate delivery cost based on destination and order total.
Request Body
json
{"stateCode": "LA","orderTotal": 25000}
Response
json
{"success": true,"data": {"cost": 2500,"maxDeliveryDays": 3,"stateCode": "LA","stateName": "Lagos"}}
Contact
Endpoints for contacting the store.
POST
/api/public/store/contactSubmit a contact form message to the vendor.
Request Body
json
{"name": "John Doe","email": "john@example.com","phone": "+234 800 123 4567","subject": "Product Inquiry","message": "Hello, I have a question about your products..."}
Response
json
{"success": true,"message": "Message sent successfully"}
Dashboard
Endpoints for dashboard statistics and analytics.
GET
/api/public/vendor/dashboard/statsGet comprehensive dashboard statistics including orders, products, and transactions.
Response
json
{"success": true,"data": {"orders": {"total": 150,"pending": 12,"completed": 130,"cancelled": 8,"totalRevenue": 2500000},"products": {"total": 48,"active": 42,"outOfStock": 6},"transactions": {"totalEarnings": 2500000,"pendingSettlements": 150000,"completedTransactions": 145}}}
GET
/api/public/vendor/dashboard/recent-orders?limit=5Get recent orders for the dashboard.
Response
json
{"success": true,"data": [{"id": "ord_abc123","orderNumber": "ORD-2024-001","customerName": "John Doe","totalAmount": 45000,"status": "pending","createdAt": "2024-01-15T10:30:00Z"}]}
GET
/api/public/vendor/dashboard/sales-chart?filter=monthGet sales chart data for visualization.
Response
json
{"success": true,"data": {"labels": ["Jan", "Feb", "Mar", "Apr"],"datasets": [{"label": "Sales","data": [120000, 190000, 300000, 250000]}]}}
Products CRUD
Endpoints for managing your products - create, read, update, and delete.
POST
/api/public/vendor/productsCreate a new product.
Request Body
json
{"name": "Premium Sneakers","description": "High-quality premium sneakers for everyday wear","price": 45000,"compareAtPrice": 55000,"categoryId": "cat_abc123","quantity": 50,"trackQuantity": true,"status": "active","visibility": "visible","images": [{"url": "https://storage.example.com/img1.jpg","altText": "Sneaker front view","isPrimary": true}],"isFeatured": false}
Response
json
{"success": true,"message": "Product created successfully","data": {"id": "prod_xyz789","name": "Premium Sneakers","price": 45000,"status": "active"}}
GET
/api/public/vendor/products?limit=50&offset=0&status=active&categoryId=xxxGet vendor products with filtering and pagination.
Response
json
{"success": true,"data": [{"id": "prod_abc123","name": "Premium Sneakers","price": 45000,"quantity": 50,"status": "active","images": ["https://..."]}],"pagination": {"total": 48,"limit": 50,"offset": 0,"hasMore": false}}
GET
/api/public/vendor/products/statsGet product statistics.
Response
json
{"success": true,"data": {"total": 48,"active": 42,"draft": 3,"inactive": 3,"outOfStock": 6,"lowStock": 8,"featured": 5}}
GET
/api/public/vendor/products/:productIdGet single product by ID.
Response
json
{"success": true,"data": {"id": "prod_abc123","name": "Premium Sneakers","description": "High-quality premium sneakers...","price": 45000,"compareAtPrice": 55000,"quantity": 50,"status": "active","images": [...],"variants": [...]}}
PUT
/api/public/vendor/products/:productIdUpdate a product.
Request Body
json
{"name": "Premium Sneakers - Updated","price": 48000,"quantity": 45}
Response
json
{"success": true,"message": "Product updated successfully","data": { ... }}
PATCH
/api/public/vendor/products/:productId/statusUpdate product status.
Request Body
json
{"status": "inactive"}
Response
json
{"success": true,"message": "Product status updated successfully"}
DELETE
/api/public/vendor/products/:productIdDelete a product (soft delete).
Response
json
{"success": true,"message": "Product deleted successfully"}
Services CRUD
Endpoints for managing your services - create, read, update, and delete.
POST
/api/public/vendor/servicesCreate a new service.
Request Body
json
{"name": "Hair Styling","description": "Professional hair styling service","price": 15000,"allowBooking": true,"images": [{"url": "https://storage.example.com/service.jpg","name": "Service Image"}]}
Response
json
{"success": true,"message": "Service created successfully","data": {"id": "svc_xyz789","name": "Hair Styling","price": 15000}}
GET
/api/public/vendor/services?limit=50&offset=0&isActive=trueGet vendor services with filtering and pagination.
Response
json
{"success": true,"data": [{"id": "svc_abc123","name": "Hair Styling","price": 15000,"isActive": true,"allowBooking": true}],"pagination": {"total": 12,"limit": 50,"offset": 0,"hasMore": false}}
GET
/api/public/vendor/services/:serviceIdGet single service by ID.
Response
json
{"success": true,"data": {"id": "svc_abc123","name": "Hair Styling","description": "Professional hair styling...","price": 15000,"isActive": true,"allowBooking": true,"variants": [...]}}
PUT
/api/public/vendor/services/:serviceIdUpdate a service.
Request Body
json
{"name": "Hair Styling - Premium","price": 18000}
Response
json
{"success": true,"message": "Service updated successfully","data": { ... }}
PATCH
/api/public/vendor/services/:serviceId/toggle-activeToggle service active status.
Response
json
{"success": true,"message": "Service status toggled successfully","data": {"isActive": false}}
DELETE
/api/public/vendor/services/:serviceIdDelete a service (soft delete).
Response
json
{"success": true,"message": "Service deleted successfully"}
Orders
Endpoints for managing and viewing orders.
GET
/api/public/vendor/orders?limit=50&offset=0&status=pending&paymentStatus=paidGet vendor orders with filtering and pagination.
Response
json
{"success": true,"data": [{"id": "ord_abc123","orderNumber": "ORD-2024-001","customerName": "John Doe","customerEmail": "john@example.com","status": "pending","paymentStatus": "paid","totalAmount": 92500,"items": [...],"createdAt": "2024-01-15T10:30:00Z"}],"pagination": {"total": 150,"limit": 50,"offset": 0,"hasMore": true}}
GET
/api/public/vendor/orders/statsGet order statistics.
Response
json
{"success": true,"data": {"total": 150,"pending": 12,"confirmed": 8,"processing": 5,"shipped": 10,"delivered": 110,"cancelled": 5,"totalRevenue": 2500000}}
GET
/api/public/vendor/orders/:orderIdGet single order by ID.
Response
json
{"success": true,"data": {"id": "ord_abc123","orderNumber": "ORD-2024-001","customerName": "John Doe","customerEmail": "john@example.com","customerPhone": "+234 800 123 4567","status": "pending","paymentStatus": "paid","paymentMethod": "card","subtotal": 90000,"shippingCost": 2500,"totalAmount": 92500,"shippingAddress": "123 Main Street, Lagos","items": [{"productId": "prod_abc123","productName": "Premium Sneakers","quantity": 2,"unitPrice": 45000,"totalPrice": 90000}],"createdAt": "2024-01-15T10:30:00Z"}}
PATCH
/api/public/vendor/orders/:orderId/statusUpdate order status.
Request Body
json
{"status": "confirmed"}
Response
json
{"success": true,"message": "Order status updated successfully","data": { ... }}
Transactions
Endpoints for viewing transactions and earnings.
GET
/api/public/vendor/transactions?limit=50&offset=0&type=payment&status=completedGet vendor transactions with filtering and pagination.
Response
json
{"success": true,"data": [{"id": "txn_abc123","orderId": "ord_xyz789","type": "payment","status": "completed","amount": 92500,"paymentMethod": "card","customerEmail": "john@example.com","createdAt": "2024-01-15T10:35:00Z"}],"pagination": {"total": 145,"limit": 50,"offset": 0,"hasMore": true}}
GET
/api/public/vendor/transactions/summary?dateFrom=2024-01-01&dateTo=2024-12-31Get transaction summary.
Response
json
{"success": true,"data": {"totalTransactions": 145,"totalAmount": 2500000,"completedAmount": 2350000,"pendingAmount": 150000,"byPaymentMethod": {"card": 1800000,"bank_transfer": 700000}}}
GET
/api/public/vendor/transactions/earnings?dateFrom=2024-01-01&dateTo=2024-12-31Get vendor earnings data.
Response
json
{"success": true,"data": {"totalEarnings": 2500000,"settledAmount": 2350000,"pendingSettlements": 150000,"thisMonth": 450000,"lastMonth": 380000,"growth": 18.4}}
Deliveries
Endpoints for managing delivery routes and settings.
GET
/api/public/vendor/deliveries?stateCode=LA&status=activeGet vendor delivery routes.
Response
json
{"success": true,"data": [{"id": "route_abc123","stateCode": "LA","stateName": "Lagos","cost": 2500,"maxDeliveryDays": 3,"status": "active"},{"id": "route_def456","stateCode": "OG","stateName": "Ogun","cost": 3500,"maxDeliveryDays": 5,"status": "active"}]}
GET
/api/public/vendor/deliveries/summaryGet delivery routes summary.
Response
json
{"success": true,"data": {"totalRoutes": 15,"activeRoutes": 12,"averageCost": 3000,"statesCovered": ["Lagos", "Ogun", "Oyo", "Abuja"]}}
JavaScript
Complete example showing how to use the Vendeey API with JavaScript.
javascript
1// Using fetch API2const API_KEY = 'vnd_your_api_key_here';3const BASE_URL = 'https://api.vendeey.com';45// Get store products6async function getProducts(page = 1, limit = 20) {7 const response = await fetch(8 `${BASE_URL}/api/public/store/products?page=${page}&limit=${limit}`,9 {10 headers: {11 'x-api-key': API_KEY,12 'Content-Type': 'application/json'13 }14 }15 );1617 if (!response.ok) {18 throw new Error(`API Error: ${response.status}`);19 }2021 return response.json();22}2324// Get single product25async function getProduct(productId) {26 const response = await fetch(27 `${BASE_URL}/api/public/store/products/${productId}`,28 {29 headers: {30 'x-api-key': API_KEY31 }32 }33 );3435 return response.json();36}3738// Create an order39async function createOrder(orderData) {40 const response = await fetch(`${BASE_URL}/api/public/store/orders`, {41 method: 'POST',42 headers: {43 'x-api-key': API_KEY,44 'Content-Type': 'application/json'45 },46 body: JSON.stringify(orderData)47 });4849 return response.json();50}5152// Reserve stock before checkout53async function reserveStock(items, paymentRef) {54 const response = await fetch(`${BASE_URL}/api/public/store/stock/reserve`, {55 method: 'POST',56 headers: {57 'x-api-key': API_KEY,58 'Content-Type': 'application/json'59 },60 body: JSON.stringify({61 paymentReference: paymentRef,62 items: items,63 paymentMethod: 'card'64 })65 });6667 return response.json();68}
React
Complete example showing how to use the Vendeey API with React.
jsx
1import { useState, useEffect } from 'react';23const API_KEY = process.env.REACT_APP_VENDEEY_API_KEY;4const BASE_URL = 'https://api.vendeey.com';56// Custom hook for fetching products7function useProducts(page = 1, limit = 20) {8 const [products, setProducts] = useState([]);9 const [loading, setLoading] = useState(true);10 const [error, setError] = useState(null);11 const [pagination, setPagination] = useState(null);1213 useEffect(() => {14 async function fetchProducts() {15 try {16 setLoading(true);17 const response = await fetch(18 `${BASE_URL}/api/public/store/products?page=${page}&limit=${limit}`,19 {20 headers: {21 'x-api-key': API_KEY,22 'Content-Type': 'application/json'23 }24 }25 );2627 if (!response.ok) throw new Error('Failed to fetch');2829 const data = await response.json();30 setProducts(data.products);31 setPagination(data.pagination);32 } catch (err) {33 setError(err.message);34 } finally {35 setLoading(false);36 }37 }3839 fetchProducts();40 }, [page, limit]);4142 return { products, loading, error, pagination };43}4445// Product List Component46function ProductList() {47 const { products, loading, error, pagination } = useProducts();4849 if (loading) return <div className="loading">Loading...</div>;50 if (error) return <div className="error">Error: {error}</div>;5152 return (53 <div className="product-grid">54 {products.map(product => (55 <ProductCard key={product.id} product={product} />56 ))}5758 {pagination?.hasMore && (59 <button onClick={() => /* load more */}>60 Load More61 </button>62 )}63 </div>64 );65}6667// Product Card Component68function ProductCard({ product }) {69 return (70 <div className="product-card">71 <img72 src={product.images[0]}73 alt={product.name}74 loading="lazy"75 />76 <h3>{product.name}</h3>77 <p className="price">78 ₦{product.price.toLocaleString()}79 </p>80 {product.compareAtPrice && (81 <p className="compare-price">82 ₦{product.compareAtPrice.toLocaleString()}83 </p>84 )}85 <button onClick={() => addToCart(product)}>86 Add to Cart87 </button>88 </div>89 );90}
Python
Complete example showing how to use the Vendeey API with Python.
python
1import requests2from typing import Optional, Dict, Any34API_KEY = 'vnd_your_api_key_here'5BASE_URL = 'https://api.vendeey.com'67class VendeeyClient:8 """Client for interacting with the Vendeey Public API"""910 def __init__(self, api_key: str):11 self.api_key = api_key12 self.session = requests.Session()13 self.session.headers.update({14 'x-api-key': api_key,15 'Content-Type': 'application/json'16 })1718 def get_store_info(self) -> Dict[str, Any]:19 """Get store information"""20 response = self.session.get(f'{BASE_URL}/api/public/store/info')21 response.raise_for_status()22 return response.json()2324 def get_products(25 self,26 page: int = 1,27 limit: int = 20,28 category_id: Optional[str] = None,29 featured: bool = False30 ) -> Dict[str, Any]:31 """Fetch products with pagination and filtering"""32 params = {'page': page, 'limit': limit}33 if category_id:34 params['categoryId'] = category_id35 if featured:36 params['featured'] = 'true'3738 response = self.session.get(39 f'{BASE_URL}/api/public/store/products',40 params=params41 )42 response.raise_for_status()43 return response.json()4445 def get_product(self, product_id: str) -> Dict[str, Any]:46 """Get single product details"""47 response = self.session.get(48 f'{BASE_URL}/api/public/store/products/{product_id}'49 )50 response.raise_for_status()51 return response.json()5253 def create_order(self, order_data: Dict[str, Any]) -> Dict[str, Any]:54 """Create a new order"""55 response = self.session.post(56 f'{BASE_URL}/api/public/store/orders',57 json=order_data58 )59 response.raise_for_status()60 return response.json()6162 def search(self, query: str, limit: int = 10) -> Dict[str, Any]:63 """Search products and categories"""64 response = self.session.get(65 f'{BASE_URL}/api/public/store/search',66 params={'q': query, 'limit': limit}67 )68 response.raise_for_status()69 return response.json()707172# Usage73client = VendeeyClient(API_KEY)7475# Get store info76store = client.get_store_info()77print(f"Store: {store['businessName']}")7879# Get products80products = client.get_products(page=1, limit=10)81for product in products['products']:82 print(f"- {product['name']}: ₦{product['price']}")
cURL
Complete example showing how to use the Vendeey API with cURL.
bash
1# Get store information2curl -X GET 'https://api.vendeey.com/api/public/store/info' \3 -H 'x-api-key: vnd_your_api_key_here' \4 -H 'Content-Type: application/json'56# Get products with pagination7curl -X GET 'https://api.vendeey.com/api/public/store/products?page=1&limit=20' \8 -H 'x-api-key: vnd_your_api_key_here'910# Get featured products11curl -X GET 'https://api.vendeey.com/api/public/store/products/featured?limit=8' \12 -H 'x-api-key: vnd_your_api_key_here'1314# Get single product15curl -X GET 'https://api.vendeey.com/api/public/store/products/prod_abc123' \16 -H 'x-api-key: vnd_your_api_key_here'1718# Search products19curl -X GET 'https://api.vendeey.com/api/public/store/search?q=sneakers&limit=10' \20 -H 'x-api-key: vnd_your_api_key_here'2122# Reserve stock for checkout23curl -X POST 'https://api.vendeey.com/api/public/store/stock/reserve' \24 -H 'x-api-key: vnd_your_api_key_here' \25 -H 'Content-Type: application/json' \26 -d '{27 "paymentReference": "ref_abc123xyz",28 "items": [29 {30 "productId": "prod_abc123",31 "quantity": 2,32 "productName": "Premium Sneakers",33 "productPrice": 4500034 }35 ],36 "paymentMethod": "card",37 "customerEmail": "customer@example.com"38 }'3940# Create an order41curl -X POST 'https://api.vendeey.com/api/public/store/orders' \42 -H 'x-api-key: vnd_your_api_key_here' \43 -H 'Content-Type: application/json' \44 -d '{45 "customerName": "John Doe",46 "customerEmail": "john@example.com",47 "customerPhone": "+234 800 123 4567",48 "paymentMethod": "card",49 "paymentReference": "ref_abc123xyz",50 "deliveryMethod": "delivery",51 "shippingAddress": "123 Main Street, Lagos",52 "items": [53 {54 "productId": "prod_abc123",55 "productName": "Premium Sneakers",56 "quantity": 2,57 "unitPrice": 4500058 }59 ],60 "subtotal": 90000,61 "shippingCost": 250062 }'6364# Verify payment65curl -X GET 'https://api.vendeey.com/api/public/payments/verify/ref_abc123xyz' \66 -H 'x-api-key: vnd_your_api_key_here'
System Blueprint
Share this with any AI coding agent to help them understand the Vendeey API system architecture and security requirements.
AI Integration Prompt
# Vendeey API Integration Blueprint
## System Overview
You are integrating with the Vendeey e-commerce API. Vendeey is a multi-vendor e-commerce platform that provides API access for ProMax plan subscribers to build custom storefronts and manage their stores programmatically.
## API Base URL
```
https://api.vendeey.com
```
## Two Types of Authentication
### 1. API Key Authentication (for Storefront/Vendor API)
For accessing store data and vendor management endpoints:
```
x-api-key: vnd_xxxxxxxxxxxxx
Content-Type: application/json
```
### 2. JWT Authentication (for User Authentication)
For user login, registration, and protected user endpoints:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
```
Or via httpOnly cookie (auth_token) - automatically sent by browser.
## Security Requirements
1. **NEVER expose the API key in client-side code** - Use server-side API routes or backend proxies
2. **Store API key in environment variables** - Never commit to version control
3. **Register allowed origins** - Only registered domains can make API requests (CORS protection)
4. **Validate all user inputs** - Sanitize data before sending to API
5. **Handle errors gracefully** - Never expose error details to end users
6. **Store JWT tokens securely** - Use httpOnly cookies when possible
## IMPORTANT: Discover Response Structures via API Calls
Before building components or interfaces, you MUST make test API calls to discover the actual response structures. Do not assume or guess the response format.
### How to Discover Response Structures:
1. Use the provided API key to make GET requests to each endpoint
2. Log the full response to see the actual data structure
3. Build your TypeScript interfaces/types based on the real response
4. Document any fields you discover for reference
### Example Discovery Flow:
```javascript
// Make a test call to discover the response structure
const response = await fetch('https://api.vendeey.com/api/public/vendor/dashboard/stats', {
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
const data = await response.json();
console.log('Dashboard Stats Response:', JSON.stringify(data, null, 2));
// Use this output to create your TypeScript interfaces
```
### Why This Matters:
- API responses may include additional fields not documented
- Field names and types are guaranteed to be accurate
- You'll discover nested objects and their structures
- Pagination formats will be clear
## Response Format
All endpoints return responses in this format:
```json
{
"success": true,
"data": { ... },
"message": "Description of result",
"pagination": {
"total": 100,
"limit": 50,
"offset": 0,
"hasMore": true
}
}
```
## Error Handling
```json
{
"success": false,
"message": "Error description",
"data": null
}
```
HTTP Status Codes:
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized (invalid/missing API key or JWT)
- 403: Forbidden (origin not allowed or insufficient permissions)
- 404: Not Found
- 429: Too Many Requests (rate limited)
- 500: Server Error
## Rate Limiting
- 100 requests per minute per API key
- Auth endpoints: 5 requests per minute (login, register)
- Forgot password: 3 requests per minute
- Implement exponential backoff on 429 responses
## API Categories
1. **Auth API** (/auth/*) - User authentication, registration, password reset
2. **Storefront API** (/api/public/store/*) - Customer-facing endpoints
3. **Payments API** (/api/public/payments/*) - Payment processing
4. **Vendor API** (/api/public/vendor/*) - Store management
## User Roles
- **user**: Regular customer account
- **vendor**: Store owner with full access
- **staff**: Vendor employee with permission-based access
- **admin**: Platform administrator
When implementing, always:
- Create a centralized API client with proper error handling
- Implement request/response logging for debugging
- Cache frequently accessed data (products, categories)
- Handle network failures gracefully with retry logic
- Store auth tokens securely and handle token expirationHow to use this prompt
Copy this prompt and paste it into your AI coding assistant (Claude, ChatGPT, Cursor, etc.) along with your specific requirements. The AI will use this context to help you build a proper integration with the Vendeey API.
User Authentication
Use this prompt to help AI agents implement complete user authentication including registration, login, password management, and session handling.
AI Integration Prompt
# Vendeey User Authentication Integration Guide
You are implementing user authentication for an application integrated with Vendeey API.
## API Base URL
```
Base URL: https://api.vendeey.com
```
## Authentication Overview
Vendeey uses JWT (JSON Web Token) authentication with httpOnly cookies for security. Tokens are automatically managed via cookies, but you can also use the Authorization header.
## User Roles
- **user**: Regular customer account
- **vendor**: Store owner with full store access
- **staff**: Vendor employee with permission-based access
- **admin**: Platform administrator
## User Registration
### Register New User
```
POST /auth/register
Content-Type: application/json
Body: {
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"password": "SecurePass123!",
"phoneNumber": "+2348012345678" // Optional
}
```
### Password Requirements
- Minimum 8 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one number (0-9)
- At least one special character (!@#$%^&*)
### Registration Response
```json
{
"success": true,
"message": "Registration successful",
"data": {
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"role": "user",
"isVerified": false
},
"accessToken": "eyJhbGciOiJIUzI1NiIs..."
}
}
```
### Registration Errors
- 400: Invalid email format
- 400: Password doesn't meet requirements
- 409: Email already registered
## User Login
### Login Request
```
POST /auth/login
Content-Type: application/json
Body: {
"emailOrPhone": "user@example.com",
"password": "SecurePass123!"
}
```
### Login Response (Regular User)
```json
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"role": "user",
"isVerified": true
}
}
}
```
### Login Response (Vendor)
```json
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "usr_abc123",
"email": "vendor@example.com",
"role": "vendor",
"vendorId": "vnd_xyz789",
"mustChangePassword": false
}
}
}
```
### Login Response (Staff)
```json
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "usr_abc123",
"email": "staff@example.com",
"role": "staff",
"vendorId": "vnd_xyz789",
"staffId": "stf_abc123",
"permissions": [
"dashboard:view",
"products:view",
"orders:view",
"orders:manage"
]
}
}
}
```
### Mandatory Password Change
If `mustChangePassword: true` in login response (new vendors/staff):
```
POST /auth/change-mandatory-password
Authorization: Bearer {accessToken}
Content-Type: application/json
Body: {
"newPassword": "NewSecurePass456!",
"confirmPassword": "NewSecurePass456!"
}
```
### Login Errors
- 400: Missing email or password
- 401: Invalid credentials
- 403: Account suspended
- 429: Too many attempts (rate limited)
## Get Current User Profile
### Check Auth Status
```
GET /auth/profile
Authorization: Bearer {accessToken}
```
Or rely on httpOnly cookie (automatically sent by browser).
### Profile Response
```json
{
"success": true,
"data": {
"id": "usr_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+2348012345678",
"role": "user",
"isVerified": true,
"createdAt": "2024-01-15T10:30:00Z"
}
}
```
## Logout
### Logout Request
```
POST /auth/logout
Authorization: Bearer {accessToken}
```
This invalidates the token and clears the httpOnly cookie.
## Password Reset Flow
### Step 1: Request Password Reset
```
POST /auth/forgot-password
Content-Type: application/json
Body: {
"email": "user@example.com"
}
```
Response (always returns success to prevent email enumeration):
```json
{
"success": true,
"message": "If an account exists, a reset email has been sent"
}
```
### Step 2: User Receives Email
Email contains a link like:
`https://yourapp.com/reset-password?token=rst_abc123xyz`
### Step 3: Reset Password
```
POST /auth/reset-password
Content-Type: application/json
Body: {
"token": "rst_abc123xyz",
"newPassword": "NewSecurePass789!"
}
```
### Reset Errors
- 400: Invalid or expired token
- 400: Password doesn't meet requirements
## Change Password (Authenticated)
```
POST /auth/change-password
Authorization: Bearer {accessToken}
Content-Type: application/json
Body: {
"currentPassword": "OldPass123!",
"newPassword": "NewPass456!",
"confirmPassword": "NewPass456!"
}
```
## Email Verification
### Request Verification Email
```
POST /auth/resend-verification
Authorization: Bearer {accessToken}
```
### Verify Email
```
POST /auth/verify-email
Content-Type: application/json
Body: {
"token": "vrf_abc123xyz"
}
```
## Token Management
### Token Storage Best Practices
- **Web apps**: Use httpOnly cookies (automatic with Vendeey)
- **Mobile apps**: Store in secure storage (Keychain/Keystore)
- **Never** store tokens in localStorage or sessionStorage
### Token Expiration
- Access tokens expire after 24 hours
- On 401 response, redirect user to login
### Handling Expired Tokens
```javascript
// Axios interceptor example
api.interceptors.response.use(
response => response,
error => {
if (error.response?.status === 401) {
// Clear local user state
// Redirect to login
window.location.href = '/login';
}
return Promise.reject(error);
}
);
```
## Rate Limiting
- Login: 5 requests per minute
- Register: 5 requests per minute
- Forgot password: 3 requests per minute
- Other auth endpoints: 10 requests per minute
## Implementation Checklist
### Registration
- [ ] Registration form with all required fields
- [ ] Real-time password strength indicator
- [ ] Password confirmation field
- [ ] Email format validation
- [ ] Phone number format validation (optional field)
- [ ] Handle registration errors (email taken, etc.)
- [ ] Show success message and redirect
### Login
- [ ] Login form with email/phone and password
- [ ] "Remember me" option (optional)
- [ ] Handle invalid credentials error
- [ ] Handle rate limiting (show countdown)
- [ ] Redirect based on user role after login
- [ ] Handle mustChangePassword redirect
### Password Reset
- [ ] "Forgot password" link on login page
- [ ] Email input form for reset request
- [ ] Reset password page with token from URL
- [ ] New password form with confirmation
- [ ] Success message and redirect to login
### Session Management
- [ ] Store user data in app state/context
- [ ] Check auth status on app load
- [ ] Handle token expiration gracefully
- [ ] Implement logout functionality
- [ ] Clear user state on logout
### Security
- [ ] Use HTTPS for all requests
- [ ] Don't log sensitive data (passwords, tokens)
- [ ] Implement CSRF protection if needed
- [ ] Validate all inputs client-side and server-sideHow to use this prompt
Copy this prompt and paste it into your AI coding assistant (Claude, ChatGPT, Cursor, etc.) along with your specific requirements. The AI will use this context to help you build a proper integration with the Vendeey API.
Storefront Integration
Use this prompt to help AI agents build a complete customer-facing storefront with products, cart, checkout, payments, and user authentication.
AI Integration Prompt
# Vendeey Storefront Integration Guide
You are building a customer-facing e-commerce storefront integrated with Vendeey API.
## API Base URL & Authentication
```
Base URL: https://api.vendeey.com
Header: x-api-key: YOUR_API_KEY
```
## IMPORTANT: Discover Actual Response Structures
Before building interfaces, make test API calls to discover actual response structures:
```javascript
const res = await fetch('https://api.vendeey.com/api/public/store/products', {
headers: { 'x-api-key': 'YOUR_API_KEY' }
});
console.log(await res.json()); // Use this to build your TypeScript types
```
The sample responses in this guide are examples - always verify with real API calls.
## User Authentication
### Registration
```
POST /auth/register
Body: {
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"password": "SecurePass123!",
"phoneNumber": "+234..."
}
```
Password requirements: 8+ chars, uppercase, lowercase, number, special char.
### Login
```
POST /auth/login
Body: {
"emailOrPhone": "user@example.com",
"password": "SecurePass123!"
}
```
Response includes accessToken and user data. Token also set in httpOnly cookie.
### Check Auth Status
```
GET /auth/profile
Header: Authorization: Bearer {accessToken}
```
### Logout
```
POST /auth/logout
```
### Forgot Password Flow
```
POST /auth/forgot-password
Body: { "email": "user@example.com" }
```
Then user receives email with reset link.
```
POST /auth/reset-password
Body: { "token": "from_email", "newPassword": "NewPass123!" }
```
## Core Endpoints
### 1. Store Information
```
GET /api/public/store/info
```
Response:
```json
{
"success": true,
"message": "Store info retrieved successfully",
"data": {
"id": "vendor-uuid",
"slug": "store-slug",
"businessName": "Store Name",
"businessType": "physical_products",
"category": "Fashion & Apparel",
"description": "Store description",
"logo": "https://...",
"coverImage": "https://...",
"brandColor": "#800040",
"location": {
"city": "",
"state": "Lagos",
"country": "Nigeria",
"address": "123 Business Street"
},
"contact": {
"firstName": "John",
"lastName": "Doe",
"email": "store@example.com",
"phone": "+234..."
},
"socialMedia": {
"instagram": "@storename",
"whatsapp": "+234...",
"facebook": "storename",
"tiktok": "@storename"
},
"productCategories": [
{ "id": "cat-uuid", "name": "Category", "description": "...", "image": "https://..." }
],
"supportsCardPayments": true,
"supportsBankTransfer": true,
"whoBearsTxnCost": "customer"
}
}
```
### Store Counts
```
GET /api/public/store/counts
```
Response:
```json
{
"success": true,
"data": {
"productsCount": "9",
"categoriesCount": "4"
}
}
```
### 2. Products
```
GET /api/public/store/products?page=1&limit=20&categoryId=xxx&featured=true
GET /api/public/store/products/:productId
GET /api/public/store/products/featured?limit=8
```
Response (products list):
```json
{
"success": true,
"data": [
{
"id": "product-uuid",
"categoryId": "cat-uuid",
"categoryName": "Electronics",
"name": "Product Name",
"description": "Full description...",
"shortDescription": "Short desc...",
"price": 65000,
"quantity": 13,
"status": "active",
"visibility": "visible",
"isFeatured": false,
"rating": 0,
"reviewCount": 0,
"images": [{ "id": "...", "url": "https://...", "isPrimary": true }]
}
],
"pagination": { "total": 9, "page": 1, "limit": 20, "hasMore": false }
}
```
### 3. Categories
```
GET /api/public/store/categories
GET /api/public/store/categories/:categoryId/products
```
Response (categories):
```json
{
"success": true,
"data": [
{
"id": "cat-uuid",
"name": "Clothing",
"description": "Category description",
"image": "https://...",
"productCount": 5
}
]
}
```
### 4. Search
```
GET /api/public/store/search?q=keyword&limit=10
```
Response:
```json
{
"success": true,
"data": {
"products": [...],
"total": 1
}
}
```
### 5. Collections
```
GET /api/public/store/collections
GET /api/public/store/collections/summary
```
Response (collections summary):
```json
{
"success": true,
"data": [
{
"id": "cat-uuid",
"name": "Clothing",
"description": "...",
"image": "https://...",
"productCount": 5
}
]
}
```
### 6. Services (for service businesses)
```
GET /api/public/store/services
```
Response:
```json
{
"success": true,
"data": {
"services": [
{
"id": "service-uuid",
"name": "Service Name",
"description": "...",
"basePrice": 0,
"allowBooking": true,
"features": [...],
"images": [...],
"variants": [{ "id": "...", "name": "Variant", "price": 35000 }]
}
]
}
}
```
## Checkout Flow (Critical - Follow Exactly)
### Step 1: Calculate Delivery Cost
```
POST /api/public/store/delivery/cost
Body: { "stateCode": "LA", "orderTotal": 25000 }
```
Response:
```json
{
"success": true,
"data": {
"deliveryCost": 5000,
"maxDeliveryDays": 3,
"isCustomRoute": true,
"isSystemFallback": false,
"stateName": "Lagos",
"zone": "South West"
}
}
```
### Step 2: Reserve Stock (Before Payment)
```
POST /api/public/store/stock/reserve
Body: {
"paymentReference": "unique_ref_123",
"items": [
{ "productId": "xxx", "quantity": 2, "productName": "...", "productPrice": 5000 }
],
"paymentMethod": "card",
"customerEmail": "customer@example.com"
}
```
Reservations expire in 15 minutes. Store the paymentReference.
### Step 3: Initialize Payment
```
POST /api/public/payments/initialize
Body: {
"amount": 52500,
"customerEmail": "customer@example.com",
"customerName": "John Doe",
"customerPhone": "+234...",
"description": "Order payment",
"successUrl": "https://yoursite.com/checkout/success?ref={reference}",
"cancelUrl": "https://yoursite.com/checkout/cancel"
}
```
Response contains `authorizationUrl` - redirect customer to this URL.
### Step 4: Verify Payment (After Redirect)
```
GET /api/public/payments/verify/:reference
```
Check if status is "success".
### Step 5: Create Order
```
POST /api/public/store/orders
Body: {
"customerName": "John Doe",
"customerEmail": "john@example.com",
"customerPhone": "+234...",
"paymentMethod": "card",
"paymentReference": "PAY_xxx",
"deliveryMethod": "delivery",
"shippingAddress": "123 Main Street",
"shippingState": "Lagos",
"items": [
{ "productId": "xxx", "productName": "...", "quantity": 2, "unitPrice": 5000 }
],
"subtotal": 10000,
"shippingCost": 2500
}
```
### If Payment Cancelled
```
POST /api/public/store/stock/cancel/:paymentReference
```
## Additional Features
### Product Reviews
```
GET /api/public/products/:productId/reviews
GET /api/public/products/:productId/reviews/summary
POST /api/public/products/:productId/reviews
```
### Coupons
```
GET /api/public/store/coupons
```
Response:
```json
{
"success": true,
"data": [
{
"id": "coupon-uuid",
"code": "SAVE20",
"name": "SAVE 20% OFF",
"type": "percentage",
"discountValue": "20.00",
"minimumOrderAmount": "1000.00",
"maximumDiscountAmount": "20000.00",
"applicability": "specific_products",
"maxTotalUsage": "100",
"maxUsagePerCustomer": "1",
"status": "active",
"isAutoApply": true,
"validFrom": "2025-09-02T23:00:00.000Z",
"validUntil": "2025-09-05T22:59:00.000Z",
"productIds": [],
"categoryIds": []
}
]
}
```
### Contact Form
```
POST /api/public/store/contact
Body: { "name": "...", "email": "...", "subject": "...", "message": "..." }
```
## Implementation Checklist
- [ ] Create API client with error handling
- [ ] User registration form with validation
- [ ] Login/logout functionality
- [ ] Forgot password flow
- [ ] Product listing with pagination
- [ ] Product detail page with images, variants
- [ ] Category navigation
- [ ] Search functionality
- [ ] Shopping cart (client-side state)
- [ ] Checkout with stock reservation
- [ ] Payment integration (Paystack redirect)
- [ ] Order confirmation page
- [ ] Handle payment success/failure redirects
- [ ] User account page (if logged in)How to use this prompt
Copy this prompt and paste it into your AI coding assistant (Claude, ChatGPT, Cursor, etc.) along with your specific requirements. The AI will use this context to help you build a proper integration with the Vendeey API.
Vendor Management
Use this prompt to help AI agents build vendor dashboard and management features with authentication.
AI Integration Prompt
# Vendeey Vendor Management Integration Guide
You are building a vendor management dashboard integrated with Vendeey API.
## API Base URL & Authentication
```
Base URL: https://api.vendeey.com
Header: x-api-key: YOUR_API_KEY
```
## IMPORTANT: Discover Actual Response Structures
Before building interfaces, make test API calls to discover actual response structures:
```javascript
const res = await fetch('https://api.vendeey.com/api/public/vendor/products', {
headers: { 'x-api-key': 'YOUR_API_KEY' }
});
console.log(await res.json()); // Use this to build your TypeScript types
```
The sample responses in this guide are examples - always verify with real API calls.
## Vendor/Staff Authentication
### Login (Same endpoint for all users)
```
POST /auth/login
Body: {
"emailOrPhone": "vendor@example.com",
"password": "SecurePass123!"
}
```
Response varies by role:
- **vendor**: Full access, includes vendorId
- **staff**: Limited access based on permissions array
### Staff Login Response Example
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "usr_abc123",
"email": "staff@example.com",
"role": "staff",
"vendorId": "vnd_xyz789",
"staffId": "stf_abc123",
"permissions": [
"dashboard:view",
"products:view",
"products:create",
"orders:view",
"orders:manage"
]
}
}
```
### Mandatory Password Change (New Vendors)
If `mustChangePassword: true` in response:
```
POST /auth/change-mandatory-password
Body: {
"newPassword": "NewSecurePass456!",
"confirmPassword": "NewSecurePass456!"
}
```
### Staff Permissions List
```
dashboard:view - View dashboard statistics
products:view - View products
products:create - Create products
products:edit - Edit products
products:delete - Delete products
services:view - View services
services:create - Create services
services:edit - Edit services
services:delete - Delete services
orders:view - View orders
orders:manage - Update order status
deliveries:view - View deliveries
deliveries:manage - Manage delivery routes
finance:view - View financial reports
transactions:view - View transactions
invoices:view - View invoices
invoices:create - Create invoices
customers:view - View customers
customers:manage - Manage customers
coupons:view - View coupons
coupons:manage - Create/edit coupons
questions:view - View product questions
questions:answer - Answer questions
pos:access - Access Point of Sale
bookings:view - View bookings
bookings:manage - Manage bookings
```
## Dashboard Endpoints
### Overview Stats
```
GET /api/public/vendor/dashboard/stats
```
Response:
```json
{
"orders": {
"totalOrders": 9,
"totalRevenue": "180000.00",
"averageOrderValue": 20000,
"pendingOrders": "0",
"processingOrders": "0",
"shippedOrders": "0",
"deliveredOrders": "2",
"cancelledOrders": "0"
},
"products": {
"totalProducts": "9",
"activeProducts": "9",
"activeInStockProducts": "9",
"draftProducts": "0",
"outOfStockProducts": "0",
"outOfStock": "0",
"featuredProducts": "1",
"lowStock": "7",
"totalValue": "737500.00"
},
"transactions": {
"totalAmount": "180000.00",
"totalTransactions": "9",
"completedTransactions": "9",
"pendingTransactions": "0",
"failedTransactions": "0",
"totalFees": "1512.50",
"netAmount": "178487.50"
}
}
```
### Recent Orders
```
GET /api/public/vendor/dashboard/recent-orders?limit=5
```
Response:
```json
[
{
"id": "6a2721d4-db06-45ef-809f-f71635e61b9f",
"orderNumber": "ACM-404910-HJR",
"customerName": "Walk-in Customer",
"customerEmail": "pos-customer@vendeey.store",
"status": "delivered",
"paymentStatus": "paid",
"paymentMethod": "pos_cash",
"totalAmount": 25000,
"currency": "NGN",
"shippingAddress": "In-Store Pickup",
"createdAt": "2026-01-03T22:40:04.912Z",
"items": [
{
"productId": "811f6cec-0341-4eea-9961-323eb2505859",
"productName": "Family Wear",
"quantity": 2,
"unitPrice": 12500,
"totalPrice": 25000,
"category": "Clothing"
}
]
}
]
```
### Sales Chart
```
GET /api/public/vendor/dashboard/sales-chart?filter=month
```
filter options: "year", "month", "3months"
Response (filter=month):
```json
{
"year": 2026,
"month": 1,
"weeklySales": [25000, 0, 0, 0],
"weeklyLabels": ["Week 1", "Week 2", "Week 3", "Week 4"]
}
```
Response (filter=3months):
```json
{
"year": 2026,
"months": ["November", "December", "January"],
"monthlySales": [0, 72500, 25000],
"monthlyLabels": ["Nov", "Dec", "Jan"]
}
```
Response (filter=year):
```json
{
"year": 2026,
"monthlySales": [25000, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"monthlyLabels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
}
```
## Products Management
### List Products
```
GET /api/public/vendor/products?limit=50&offset=0&status=active&categoryId=xxx
```
Response:
```json
{
"products": [
{
"id": "916a851f-4bca-4f0e-bb68-d251ae769694",
"vendorId": "4d0bcbe7-5a9a-41b0-91c9-6e62d7bcb48b",
"categoryId": "6dcee269-ba6c-4cc0-a876-86a8a5f6ebbe",
"categoryName": "Electronics",
"name": "Hp Deskjek Printer",
"description": "Discover the exceptional quality of Hp DeskJek Printer...",
"shortDescription": "Your all-in-one wireless printer for crisp documents and vibrant photos.",
"price": 65000,
"sku": null,
"barcode": null,
"trackQuantity": true,
"quantity": 13,
"allowBackorder": false,
"weight": 4.2,
"dimensions": {
"length": 42,
"width": 32,
"height": 19
},
"status": "active",
"visibility": "visible",
"publishedAt": "2025-11-28T14:53:16.109Z",
"seoTitle": "HP DeskJet Wireless Printer for Home & Office",
"seoDescription": "Buy the HP DeskJet wireless printer in Nigeria...",
"tags": ["printer", "hp", "deskjet", "wireless", "home", "office"],
"sortOrder": "0",
"isFeatured": false,
"requiresShipping": true,
"taxable": true,
"videoUrl": null,
"rating": 0,
"reviewCount": 0,
"createdAt": "2025-11-28T14:53:16.109Z",
"updatedAt": "2025-12-25T13:27:00.059Z",
"images": [
{
"id": "492cc93f-d617-4cac-9f35-87a0fcd0e3bf",
"url": "https://vendeey.b-cdn.net/images/397dd85e-2b30-4def-9342-180fbd25f504.jpg",
"isPrimary": true,
"sortOrder": "0"
}
]
}
],
"pagination": {
"total": 9,
"limit": 50,
"offset": 0,
"hasMore": false
}
}
```
### Create Product
```
POST /api/public/vendor/products
Body: {
"name": "Product Name",
"description": "Description...",
"price": 5000,
"compareAtPrice": 6000,
"categoryId": "cat_xxx",
"quantity": 50,
"trackQuantity": true,
"status": "active",
"visibility": "visible",
"images": [
{ "url": "https://...", "altText": "...", "isPrimary": true }
],
"isFeatured": false
}
```
### Update Product
```
PUT /api/public/vendor/products/:productId
Body: { "name": "Updated Name", "price": 5500 }
```
### Update Product Status
```
PATCH /api/public/vendor/products/:productId/status
Body: { "status": "inactive" }
```
Status options: "active", "inactive", "draft"
### Delete Product
```
DELETE /api/public/vendor/products/:productId
```
### Product Stats
```
GET /api/public/vendor/products/stats
```
Response:
```json
{
"success": true,
"data": {
"totalProducts": "9",
"activeProducts": "9",
"activeInStockProducts": "9",
"draftProducts": "0",
"outOfStockProducts": "0",
"outOfStock": "0",
"featuredProducts": "1",
"lowStock": "7",
"totalValue": "737500.00"
}
}
```
## Services Management (for service businesses)
### List Services
```
GET /api/public/vendor/services?limit=50&isActive=true
```
### Create Service
```
POST /api/public/vendor/services
Body: {
"name": "Service Name",
"description": "...",
"price": 15000,
"allowBooking": true
}
```
### Update Service
```
PUT /api/public/vendor/services/:serviceId
```
### Toggle Service Active
```
PATCH /api/public/vendor/services/:serviceId/toggle-active
```
### Delete Service
```
DELETE /api/public/vendor/services/:serviceId
```
## Orders Management
### List Orders
```
GET /api/public/vendor/orders?limit=50&status=pending&paymentStatus=paid
```
status: "pending", "confirmed", "processing", "shipped", "delivered", "cancelled", "approved"
paymentStatus: "pending", "paid", "failed", "refunded"
Response:
```json
{
"success": true,
"data": [
{
"id": "6a2721d4-db06-45ef-809f-f71635e61b9f",
"orderNumber": "ACM-404910-HJR",
"vendorId": "4d0bcbe7-5a9a-41b0-91c9-6e62d7bcb48b",
"customerId": null,
"customerName": "Walk-in Customer",
"customerEmail": "pos-customer@vendeey.store",
"customerPhone": null,
"status": "delivered",
"paymentStatus": "paid",
"paymentMethod": "pos_cash",
"subtotal": 25000,
"shippingCost": 0,
"tax": 0,
"discount": 0,
"totalAmount": 25000,
"currency": "NGN",
"shippingAddress": "In-Store Pickup",
"createdAt": "2026-01-03T22:40:04.912Z",
"items": [
{
"id": "2c57666f-6031-4f9a-9458-8eea513f7427",
"productId": "811f6cec-0341-4eea-9961-323eb2505859",
"productName": "Family Wear",
"quantity": 2,
"unitPrice": 12500,
"totalPrice": 25000,
"category": "Clothing"
}
]
}
],
"pagination": { "total": 9, "limit": 50, "offset": 0, "hasMore": false }
}
```
### Get Order Details
```
GET /api/public/vendor/orders/:orderId
```
### Update Order Status
```
PATCH /api/public/vendor/orders/:orderId/status
Body: { "status": "confirmed" }
```
### Order Stats
```
GET /api/public/vendor/orders/stats
```
Response:
```json
{
"success": true,
"data": {
"totalOrders": 9,
"totalRevenue": "180000.00",
"averageOrderValue": 20000,
"pendingOrders": "0",
"processingOrders": "0",
"shippedOrders": "0",
"deliveredOrders": "2",
"cancelledOrders": "0"
}
}
```
## Transactions & Earnings
### List Transactions
```
GET /api/public/vendor/transactions?type=payment&status=completed&limit=50
```
Response:
```json
{
"success": true,
"data": [
{
"id": "6cf6d5f0-96eb-45d4-8521-853bfac1612f",
"orderId": "1f0c3def-38fe-4a27-b9c2-3abd2d09d906",
"vendorId": "4d0bcbe7-5a9a-41b0-91c9-6e62d7bcb48b",
"customerEmail": "customer@example.com",
"type": "payment",
"status": "completed",
"amount": "12500.00",
"currency": "NGN",
"paymentMethod": "card",
"paymentGateway": "paystack",
"paymentReference": "n7hzdfymgq",
"transactionFee": "0.00",
"platformFee": "125.00",
"gatewayFee": "288.00",
"netAmount": "12500.00",
"isSettled": false,
"description": "Payment for order via card",
"processedAt": "2025-12-04T02:36:41.177Z",
"createdAt": "2025-12-04T02:36:41.177Z"
}
],
"pagination": { "total": "9", "limit": 50, "offset": 0, "hasMore": false }
}
```
### Transaction Summary
```
GET /api/public/vendor/transactions/summary?dateFrom=2024-01-01&dateTo=2024-12-31
```
Response:
```json
{
"success": true,
"data": {
"totalAmount": "180000.00",
"totalTransactions": "9",
"completedTransactions": "9",
"pendingTransactions": "0",
"failedTransactions": "0",
"totalFees": "1512.50",
"netAmount": "178487.50"
}
}
```
### Earnings Data
```
GET /api/public/vendor/transactions/earnings
```
Response:
```json
{
"success": true,
"data": {
"totalEarnings": 178487.5,
"transactionFee": 1512.5,
"pendingTransactionFee": 1512.5,
"pendingSettlements": 153487.5,
"settledAmount": 25000,
"totalTransactions": 9,
"pendingTransactions": 8,
"settledTransactions": 1,
"totalCustomers": 2
}
}
```
## Delivery Routes
### List Delivery Routes
```
GET /api/public/vendor/deliveries?stateCode=LA
```
### Delivery Summary
```
GET /api/public/vendor/deliveries/summary
```
## Categories Management
### List Categories
```
GET /api/public/vendor/categories?limit=50&offset=0
```
Response:
```json
{
"success": true,
"data": [
{
"id": "6dcee269-ba6c-4cc0-a876-86a8a5f6ebbe",
"name": "Electronics",
"description": "Electronic devices and accessories",
"image": "https://vendeey.b-cdn.net/images/category.jpg",
"productCount": 5,
"dateCreated": "2025-11-28T14:53:16.109Z"
}
],
"pagination": {
"total": 3,
"limit": 50,
"offset": 0,
"hasMore": false
}
}
```
### Get Single Category
```
GET /api/public/vendor/categories/:categoryId
```
### Categories Dropdown (Simplified)
```
GET /api/public/vendor/categories/dropdown
```
### Create Category
```
POST /api/public/vendor/categories
Body: {
"name": "Category Name",
"description": "Description of the category",
"image": "https://..." // optional
}
```
Response:
```json
{
"success": true,
"message": "Category created successfully",
"data": {
"id": "cat_xxx123",
"name": "Category Name",
"description": "Description of the category",
"image": null,
"createdAt": "2026-01-05T10:00:00.000Z"
}
}
```
### Update Category
```
PUT /api/public/vendor/categories/:categoryId
Body: {
"name": "Updated Name",
"description": "Updated description",
"image": "https://..."
}
```
Response:
```json
{
"success": true,
"message": "Category updated successfully",
"data": { ... }
}
```
### Delete Category
```
DELETE /api/public/vendor/categories/:categoryId
```
Response:
```json
{
"success": true,
"message": "Category deleted successfully"
}
```
### Check Category Name Availability
```
GET /api/public/vendor/categories/check-name?name=Electronics&excludeId=xxx
```
Response:
```json
{
"success": true,
"data": {
"available": true,
"name": "Electronics"
}
}
```
## Customers Management
### List Customers
```
GET /api/public/vendor/customers?search=john&limit=50&offset=0
```
### Online Shop Customers (from orders)
```
GET /api/public/vendor/customers/online?limit=50
```
### Top Customers (by total spent)
```
GET /api/public/vendor/customers/top?limit=10
```
### Recent Customers
```
GET /api/public/vendor/customers/recent?limit=10
```
## Implementation Checklist
- [ ] Login page for vendor/staff
- [ ] Handle mustChangePassword redirect
- [ ] Store and manage JWT token
- [ ] Permission-based UI rendering (for staff)
- [ ] Dashboard with stats cards
- [ ] Recent orders widget
- [ ] Sales chart visualization
- [ ] Products list with filters
- [ ] Product create/edit forms (if has permission)
- [ ] Product image upload handling
- [ ] Orders list with status filters
- [ ] Order detail view
- [ ] Order status update (if has permission)
- [ ] Transaction history
- [ ] Earnings reports
- [ ] Services management (if applicable)
- [ ] Delivery routes management
- [ ] Logout functionalityHow to use this prompt
Copy this prompt and paste it into your AI coding assistant (Claude, ChatGPT, Cursor, etc.) along with your specific requirements. The AI will use this context to help you build a proper integration with the Vendeey API.
Staff Dashboard
Use this prompt to help AI agents build a complete staff/vendor dashboard where vendors and their staff can login to manage products, categories, orders, transactions, and view analytics.
AI Integration Prompt
# Vendeey Staff Dashboard Integration Guide
You are building a staff/vendor dashboard where store owners (vendors) and their staff members can login and manage the store based on their permissions.
## API Base URL & Authentication
```
Base URL: https://api.vendeey.com
Header: x-api-key: YOUR_API_KEY
```
## IMPORTANT: Discover Actual Response Structures
Before building interfaces, make test API calls to discover actual response structures:
```javascript
const res = await fetch('https://api.vendeey.com/api/public/vendor/dashboard/stats', {
headers: { 'x-api-key': 'YOUR_API_KEY' }
});
console.log(await res.json()); // Use this to build your TypeScript types
```
The sample responses in this guide are examples - always verify with real API calls.
## Authentication Flow
### Login (Same endpoint for vendors and staff)
```
POST /auth/login
Body: {
"emailOrPhone": "user@example.com",
"password": "SecurePass123!"
}
```
### Response Structure
```json
{
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"role": "vendor" | "staff",
"vendorId": "vnd_xyz789",
"staffId": "stf_abc123", // Only for staff
"permissions": [...], // Only for staff
"mustChangePassword": false
}
}
```
### Role-Based Access
- **vendor**: Full access to all features. No permission checks needed.
- **staff**: Access based on permissions array. Check permissions before showing UI elements.
### Mandatory Password Change
If `mustChangePassword: true` in login response:
```
POST /auth/change-mandatory-password
Header: Authorization: Bearer {accessToken}
Body: {
"newPassword": "NewSecurePass456!",
"confirmPassword": "NewSecurePass456!"
}
```
## Staff Permissions Reference
```
dashboard:view - View dashboard statistics
products:view - View products list
products:create - Create new products
products:edit - Edit existing products
products:delete - Delete products
orders:view - View orders list
orders:manage - Update order status
finance:view - View financial reports
transactions:view - View transaction history
customers:view - View customer list
coupons:view - View coupons
coupons:manage - Create/edit coupons
```
## Permission-Based UI Pattern
```javascript
// Store user data after login
const user = loginResponse.user;
const isVendor = user.role === 'vendor';
const permissions = user.permissions || [];
// Check permission helper
function hasPermission(permission) {
return isVendor || permissions.includes(permission);
}
// Use in UI
if (hasPermission('products:view')) {
// Show products menu item
}
if (hasPermission('products:create')) {
// Show "Add Product" button
}
if (hasPermission('orders:manage')) {
// Show order status update controls
}
```
## Dashboard Endpoints
### Dashboard Stats (requires: dashboard:view)
```
GET /api/public/vendor/dashboard/stats
```
Response:
```json
{
"success": true,
"data": {
"orders": {
"totalOrders": 9,
"totalRevenue": "180000.00",
"averageOrderValue": 20000,
"pendingOrders": "0",
"deliveredOrders": "2"
},
"products": {
"totalProducts": "9",
"activeProducts": "9",
"lowStock": "7",
"totalValue": "737500.00"
},
"transactions": {
"totalAmount": "180000.00",
"totalTransactions": "9",
"netAmount": "178487.50"
}
}
}
```
### Recent Orders (requires: orders:view)
```
GET /api/public/vendor/dashboard/recent-orders?limit=5
```
### Sales Chart (requires: dashboard:view)
```
GET /api/public/vendor/dashboard/sales-chart?filter=month
```
filter options: "year", "month", "3months"
Response (filter=month):
```json
{
"success": true,
"data": {
"year": 2026,
"month": 1,
"weeklySales": [25000, 0, 0, 0],
"weeklyLabels": ["Week 1", "Week 2", "Week 3", "Week 4"]
}
}
```
## Products Management
### List Products (requires: products:view)
```
GET /api/public/vendor/products?limit=50&offset=0&status=active
```
### Get Product (requires: products:view)
```
GET /api/public/vendor/products/:productId
```
### Create Product (requires: products:create)
```
POST /api/public/vendor/products
Body: {
"name": "Product Name",
"description": "Description...",
"price": 5000,
"compareAtPrice": 6000,
"categoryId": "cat_xxx",
"quantity": 50,
"trackQuantity": true,
"status": "active",
"images": [{ "url": "https://...", "isPrimary": true }],
"isFeatured": false
}
```
### Update Product (requires: products:edit)
```
PUT /api/public/vendor/products/:productId
Body: { "name": "Updated Name", "price": 5500 }
```
### Delete Product (requires: products:delete)
```
DELETE /api/public/vendor/products/:productId
```
### Product Stats
```
GET /api/public/vendor/products/stats
```
## Categories Management
### List Categories (requires: products:view)
```
GET /api/public/vendor/categories?limit=50&offset=0
```
Response:
```json
{
"success": true,
"data": [
{
"id": "6dcee269-ba6c-4cc0-a876-86a8a5f6ebbe",
"name": "Electronics",
"description": "Electronic devices and accessories",
"image": "https://vendeey.b-cdn.net/images/category.jpg",
"productCount": 5,
"dateCreated": "2025-11-28T14:53:16.109Z"
}
],
"pagination": { "total": 3, "limit": 50, "offset": 0, "hasMore": false }
}
```
### Get Single Category (requires: products:view)
```
GET /api/public/vendor/categories/:categoryId
```
### Categories Dropdown (requires: products:view)
```
GET /api/public/vendor/categories/dropdown
```
Returns simplified list: `[{ "id": "...", "name": "..." }]`
### Create Category (requires: products:create)
```
POST /api/public/vendor/categories
Body: {
"name": "Category Name",
"description": "Description of the category",
"image": "https://..." // optional
}
```
Response:
```json
{
"success": true,
"message": "Category created successfully",
"data": { "id": "cat_xxx", "name": "Category Name", ... }
}
```
### Update Category (requires: products:edit)
```
PUT /api/public/vendor/categories/:categoryId
Body: {
"name": "Updated Name",
"description": "Updated description",
"image": "https://..."
}
```
Response:
```json
{
"success": true,
"message": "Category updated successfully",
"data": { ... }
}
```
### Delete Category (requires: products:delete)
```
DELETE /api/public/vendor/categories/:categoryId
```
Response:
```json
{
"success": true,
"message": "Category deleted successfully"
}
```
### Check Category Name Availability (requires: products:view)
```
GET /api/public/vendor/categories/check-name?name=Electronics&excludeId=xxx
```
Response:
```json
{
"success": true,
"data": { "available": true, "name": "Electronics" }
}
```
## Orders Management
### List Orders (requires: orders:view)
```
GET /api/public/vendor/orders?limit=50&status=pending&paymentStatus=paid
```
status: "pending", "confirmed", "processing", "shipped", "delivered", "cancelled", "approved"
paymentStatus: "pending", "paid", "failed", "refunded"
### Get Order Details (requires: orders:view)
```
GET /api/public/vendor/orders/:orderId
```
### Update Order Status (requires: orders:manage)
```
PATCH /api/public/vendor/orders/:orderId/status
Body: { "status": "confirmed" }
```
### Order Stats
```
GET /api/public/vendor/orders/stats
```
## Transactions (requires: transactions:view)
### List Transactions
```
GET /api/public/vendor/transactions?type=payment&status=completed&limit=50
```
### Transaction Summary
```
GET /api/public/vendor/transactions/summary?dateFrom=2024-01-01&dateTo=2024-12-31
```
### Earnings Data (requires: finance:view)
```
GET /api/public/vendor/transactions/earnings
```
## Customers Management (requires: customers:view)
### List Customers
```
GET /api/public/vendor/customers?search=john&limit=50&offset=0
```
### Online Shop Customers
```
GET /api/public/vendor/customers/online?limit=50
```
### Top Customers
```
GET /api/public/vendor/customers/top?limit=10
```
### Recent Customers
```
GET /api/public/vendor/customers/recent?limit=10
```
## Navigation Structure
```javascript
const navItems = [
{
name: "Dashboard",
href: "/dashboard",
permission: "dashboard:view"
},
{
name: "Products",
href: "/products",
permission: "products:view"
},
{
name: "Orders",
href: "/orders",
permission: "orders:view"
},
{
name: "Customers",
href: "/customers",
permission: "customers:view"
},
{
name: "Transactions",
href: "/transactions",
permission: "transactions:view"
},
{
name: "Finance",
href: "/finance",
permission: "finance:view"
}
];
// Filter based on permissions
const visibleNavItems = navItems.filter(item =>
hasPermission(item.permission)
);
```
## Implementation Checklist
### Authentication
- [ ] Login page with email/password form
- [ ] Handle login response and store token
- [ ] Handle mustChangePassword redirect
- [ ] Store user role and permissions
- [ ] Implement hasPermission helper function
- [ ] Logout functionality (clear token)
### Dashboard Page
- [ ] Stats cards (orders, products, revenue)
- [ ] Recent orders widget
- [ ] Sales chart (line/bar chart)
- [ ] Wrap with permission check: dashboard:view
### Products Page
- [ ] Products list with search and filters
- [ ] Add Product button (if products:create)
- [ ] Edit button on each product (if products:edit)
- [ ] Delete button on each product (if products:delete)
- [ ] Product create/edit form
- [ ] Image upload handling
- [ ] Wrap with permission check: products:view
### Categories Section
- [ ] Categories list view
- [ ] Create category form (if products:create)
- [ ] Edit/delete category (if has permission)
### Orders Page
- [ ] Orders list with status filters
- [ ] Order detail modal/page
- [ ] Status update dropdown (if orders:manage)
- [ ] Wrap with permission check: orders:view
### Transactions Page
- [ ] Transaction list with filters
- [ ] Transaction summary cards
- [ ] Date range filter
- [ ] Wrap with permission check: transactions:view
### Finance Page
- [ ] Earnings overview
- [ ] Revenue charts
- [ ] Wrap with permission check: finance:view
### Navigation
- [ ] Sidebar/top navigation
- [ ] Filter nav items based on permissions
- [ ] Show user name and role
- [ ] Logout button
### Access Denied Component
- [ ] Create reusable "Access Denied" component
- [ ] Show when user lacks required permission
- [ ] Provide back/home navigation optionsHow to use this prompt
Copy this prompt and paste it into your AI coding assistant (Claude, ChatGPT, Cursor, etc.) along with your specific requirements. The AI will use this context to help you build a proper integration with the Vendeey API.
Base URL
All API requests should be made to the following base URL:
https://api.vendeey.comReady to Get Started?
Upgrade to ProMax and start integrating your Vendeey store data into your custom applications today.