OP 07 August, 2025 - 10:25 PM
(This post was last modified: 07 August, 2025 - 10:25 PM by ogplug. Edited 1 time in total.)
Hey everyone,
I do freelance development work for various stores within this market. If a storefront in this market has made you say "Wow", I probably made it.
I'm also much more affordable than over full-stack devs in this market.
Message me on TG here if you'd like a quote, or just want to discuss ideas.
Each store comes with the following features:
I also work very fast. I can have most stores finished within a week.
For privacy reasons, I will not share my clients in which I've developed for, but I can share examples/screenshots of my design style over DM's.
Object, Roles & General API Overview:
I do freelance development work for various stores within this market. If a storefront in this market has made you say "Wow", I probably made it.
I'm also much more affordable than over full-stack devs in this market.
Message me on TG here if you'd like a quote, or just want to discuss ideas.
Each store comes with the following features:
- Custom Built UI/UX: Most other developers use a singular template, and build custom stores off of that. Each store of mine is built custom from the ground up.
- Built with Typescript, React, Tailwind
- Built with Typescript, React, Tailwind
- Safe & Private Hosting: Only utilizing the safest hosting practices to keep you safe.
- Utilizing MongoDB on your own privately hosted VPS and a custom API wrapper to interact with the database.
- Utilizing MongoDB on your own privately hosted VPS and a custom API wrapper to interact with the database.
- User Authentication & Role System: Guest, User, Reseller, Staff, and Admin roles available.
- Category, Product, and Subcategory System: This is the typical system in which stores in this market use, to allow for virtual stock to be delivered to customers.
- Cart System: Users can add several items to their cart and check out.
- Built-In Replacement System: If a user receives an item that they need replaced, they will have the option to replace items directly from their order page only while that item is within the specified warranty period.
- Replacements can be enabled/disabled, and the warranty time can be adjusted on a per-product basis.
- For items of abundance, you can enable "auto-replace", with a max-replacement count of 3. This means that users items will automatically be replaced (skipping staff/admin approval), but after the 3rd replacement, it will need to be approved/denied by staff/admins.
- The Admin & Staff roles have access to a page called "Replacement Requests". This is a dashboard in which the replacement requests can be approved or denied. If approved, the staff/admin is presented with 3 items taken from stock, where they must choose one of them. Admins can deliver custom stock as well.
- This system decreases replacement wait time, reduces the number of tickets, and increases customer retention significantly.
- Replacements can be enabled/disabled, and the warranty time can be adjusted on a per-product basis.
- Balance / Top Up System: Users can top up their balance directly within their dashboard.
- Review & Reward System: The review system is built-in with the option to add a % reward per 5-star review. This can be enabled/disabled/customized within your Admin dashboard.
- User Dashboard: Each user will have their own dashboard where they can view their order history, top up their balance, and edit their account settings.
- Advanced Admin Dashboard: The admin dashboard is complex and designed to give you ease-of-access:
- Overview: A neatly presented overview of your sales, with dynamic charts and graphs.
- Products: This is the main area in which you can view all of your products in a table. You can view/add/edit categories, view/add/edit products, and view/add/edit subcategories.
- Edit Product Page: You can edit the Product Title, Product Description, Category, Enabled/Disabled, and edit the Replacement Settings (such as warranty time/auto-replace/etc).
- Product Subcategories: From the "Edit Product" page, you can also add the subcategories and corresponding stock. Each subcategory has it's own price, min/max quantity (default of 1 & 0 [infinite]).
- Product Subcategories: From the "Edit Product" page, you can also add the subcategories and corresponding stock. Each subcategory has it's own price, min/max quantity (default of 1 & 0 [infinite]).
- Edit Product Page: You can edit the Product Title, Product Description, Category, Enabled/Disabled, and edit the Replacement Settings (such as warranty time/auto-replace/etc).
- Orders: All orders that the site receives are displayed here.
- Easy Details Access: You can view in-depth information on each order directly from the table, as well as the user profile of the purchasing user.
- Dynamic Search & Sorting: You can search and sort orders by various criteria.
- Manual Approval: You can manually approve open orders to be delivered to customers.
- Order Gifting: You can select a user in which to gift an order to. This will automatically create the order, approve the order, and deliver their stock. It will appear in their order history as a gift.
- Easy Details Access: You can view in-depth information on each order directly from the table, as well as the user profile of the purchasing user.
- Users: All users listed in a paginated table.
- Detailed User Objects: You can view all data for each user, including their balance, total spend, email, order history, and current cart. Literally
- User Promotion: You can promote a user to "RESELLER". This role is the same as user, except they're given their own account-specific discount.
- Detailed User Objects: You can view all data for each user, including their balance, total spend, email, order history, and current cart. Literally
- Replacements: This is table view in which replacements appear. This will be the main page that "STAFF" roles have access to.
- Reviews: A paginated list of all the product reviews. All reviews are editable, and deletable!
- Analytics: An advanced analytics system which allows you to view revenue from different time-frames. This can choose between all products, specific products, specific subcategories, etc..
- Admin Settings: This is where you can customize your store name, description, enabled payment methods, external links (navbar / footer links), review settings (enable review rewards), and a scrolling/static announcement bar with several presets.
- Overview: A neatly presented overview of your sales, with dynamic charts and graphs.
- Email Integrations: I can setup transactional emails, account utility emails, email campaign dashboard, etc.
- Everything API Accessible: If you know what this means, you know it's good. The entire
- Store Transitioning: I will work hands-on with you and/or your developer to get your products from one store moved over to our new and improved database. I can handle the data reformatting.
- Custom Requests: I can add whatever you need to the site. Either frontend, user-experience based, or admin features to make your life easier. I do everything development and hosting wise, so just lmk and I'll do it for you.
I also work very fast. I can have most stores finished within a week.
For privacy reasons, I will not share my clients in which I've developed for, but I can share examples/screenshots of my design style over DM's.
Object, Roles & General API Overview:
Code:
# Virtual Store API - Complete Documentation v2.0
## Table of Contents
1. [**Introduction & Core Concepts**](#1-introduction--core-concepts)
* [Base URL](#base-url)
* [Authentication Flow (JWT)](#authentication-flow-jwt)
* [User Roles & Permissions](#user-roles--permissions)
2. [**Data Models (The Database Schema)**](#2-data-models-the-database-schema)
* [User](#user-model)
* [Auth](#auth-model-internal)
* [Product](#product-model)
* [Subcategory](#subcategory-model)
* [Stock](#stock-model)
* [Category](#category-model)
* [Order](#order-model)
* [Review](#review-model)
* [ReplacementRequest](#replacementrequest-model)
* [BalanceTransaction](#balancetransaction-model)
* [StoreConfig](#storeconfig-model)
* [Blacklist](#blacklist-model)
3. [**API Endpoints**](#3-api-endpoints)
* [Group 1: Public & Authentication](#group-1-public--authentication)
* [Group 2: Store & Product Discovery (Guest+)](#group-2-store--product-discovery-guest)
* [Group 3: User Account & Cart (User/Reseller/Staff)](#group-3-user-account--cart-userresellerstaff)
* [Group 4: Orders & Reviews (User/Reseller/Staff)](#group-4-orders--reviews-userresellerstaff)
* [Group 5: Staff & Admin Endpoints](#group-5-staff--admin-endpoints)
* [Staff: Replacement Management](#staff-replacement-management)
* [Admin: Full Management](#admin-full-management)
* [Group 6: Webhooks (Server-to-Server)](#group-6-webhooks-server-to-server)
---
## 1. Introduction & Core Concepts
This document provides a comprehensive overview of the Virtual Store API. It is designed to be the single source of truth for frontend development and integration.
### Base URL
All API endpoints are relative to their respective base URLs:
* **Frontend Application:** `https://ezgcs.fo`
* **Backend API:** `https://api.ezgcs.fo`
### Authentication Flow (JWT)
The API is stateless and uses JSON Web Tokens (JWT) for authentication. Every request that requires authentication must include an `Authorization` header.
**Header Format:** `Authorization: Bearer <your_jwt_token>`
**The flow is as follows:**
1. A new visitor (Guest) has no token. Their first action should be to call `GET /api/public/guest/token` to receive a temporary guest token.
2. This guest token must be stored and sent with all subsequent browsing requests.
3. When the user registers (`POST /api/auth/register`) or logs in (`POST /api/auth/login`), they receive a new, long-lived token.
4. This new token **replaces** the guest token in storage and is used for all future authenticated requests.
### User Roles & Permissions
The API enforces a strict role-based access control (RBAC) system. A user's role is embedded in their JWT and checked by middleware on the backend.
* **`GUEST`**: The default, unauthenticated role. Can browse products and store configuration.
* **`USER`**: The standard role after registration. Can manage their profile, cart, orders, reviews, and replacements.
* **`RESELLER`**: Promoted by an admin. Inherits all `USER` permissions and receives a custom percentage discount at checkout.
* **`STAFF`**: Promoted by an admin. Inherits all `USER` permissions and gains access to a special dashboard for managing user replacement requests.
* **`ADMIN`**: The super-user. Has full access to all API endpoints, including all other users' data and all store settings. Inherits `STAFF` permissions.
---
## 2. Data Models (The Database Schema)
This section describes the structure of the core data objects stored in the MongoDB database.
### User Model
*Stores public-facing and functional data for a registered user.*
* `_id` (String - UUID)
* `authId` (String - UUID): A link to the internal `Auth` document.
* `username` (String): Unique username.
* `email` (String): Unique email address.
* `role` (String): Enum `['USER', 'RESELLER', 'STAFF', 'ADMIN']`.
* `balance` (Number): The user's store credit balance.
* `discount` (Number): The reseller-specific discount percentage (e.g., `15.0` for 15%).
* `cart` (Array of Objects): The user's current shopping cart.
* `subcategoryId` (String - UUID)
* `amount` (Integer)
* `creation_unix` (Integer): Unix timestamp of registration.
### Auth Model (Internal)
*Stores private, authentication-related data. Not directly exposed via API.*
* `_id` (String - UUID)
* `email` (String)
* `password` (String - Hashed)
* `role` (String)
### Product Model
*A top-level container for a purchasable item.*
* `_id` (String - UUID)
* `enabled` (Boolean): Controls visibility for non-admin users.
* `title` (String): e.g., "Amazon Gift Card".
* `description` (String)
* `category` (String - UUID): The ID of the parent `Category`.
* `product_image_url` (String)
* `average_rating` (Number): A cached, rounded average (0-5) of all its reviews.
* `review_count` (Number): A cached count of all its reviews.
* `starting_at` (Number): A cached value of the lowest price among all its `Subcategories`.
* `replacement_settings` (Object):
* `replace_enabled` (Boolean)
* `auto_replace_enabled` (Boolean)
* `auto_replace_max_before_approval` (Integer)
* `warranty_time` (Integer): Warranty duration in seconds.
### Subcategory Model
*The actual purchasable variant of a product.*
* `_id` (String - UUID)
* `product` (String - UUID): The ID of the parent `Product`.
* `title` (String): e.g., "$50 Card".
* `price` (Number): The fixed price for this item. **This is the single source of truth for pricing.**
* `stock_count` (Number): A cached count of `is_sold: false` stock items.
### Stock Model
*A single, deliverable unit of a subcategory.*
* `_id` (String - UUID)
* `subcategory` (String - UUID)
* `product` (String - UUID)
* `deliverable` (String): The virtual item itself (e.g., "KEY-1234-ABCD-5678").
* `is_sold` (Boolean): `false` if available, `true` if sold.
* `sold_at` (Integer): Unix timestamp of sale.
* `order` (String - UUID): The order this item was sold in.
### Category Model
*Used to group products.*
* `_id` (String - UUID)
* `title` (String)
* `hex_code` (String): e.g., "#FF5733".
### Order Model
*Records a completed or pending purchase.*
* `_id` (String - UUID)
* `buyer` (String - UUID): The purchasing `User`.
* `product_title` (String): A snapshot of the item name at time of purchase.
* `product_image_url` (String): A snapshot of the image URL.
* `amount` (Integer): Total quantity of items in the order.
* `total_price` (Number): Final price paid after discounts.
* `payment_method` (String): e.g., "HOODPAY", "BALANCE".
* `status` (String): Enum `['PENDING', 'COMPLETED', 'FAILED', 'CANCELLED', 'EXPIRED']`.
* `hoodpay_invoice_id` (String): The link to the payment gateway's record.
* `cartSnapshot` (Array of Objects): A permanent record of the user's cart at the time of checkout. This is the source of truth for fulfillment.
* `deliverables` (Array of Strings): Populated upon successful fulfillment.
* `replacements` (Array of Strings): Populated with new deliverables if a replacement is approved.
* `creation_unix` (Integer)
### Review Model
*A user's review of a purchased product.*
* `_id` (String - UUID)
* `orderId` (String - UUID): The order this review is for (ensures one review per order).
* `productId` (String - UUID)
* `reviewed_by` (String): Username or "Anonymous".
* `rating` (Integer): 1-5.
* `text_review` (String)
* `product_name` (String): Denormalized for performance.
* `product_image` (String): Denormalized for performance.
* `creation_unix` (Integer)
### ReplacementRequest Model
*A user's request for a replacement, managed by Staff/Admins.*
* `_id` (String - UUID)
* `user` (String - UUID)
* `order` (String - UUID)
* `subcategory` (String - UUID)
* `original_deliverable` (String)
* `status` (String): Enum `['PENDING', 'APPROVED', 'DENIED']`.
* `reason_denied` (String)
* `resolved_by` (String - UUID): The Staff/Admin who handled the request.
* `resolved_at` (Integer)
* `creation_unix` (Integer)
### BalanceTransaction Model
*Records a user's balance top-up.*
* ... (similar to `Order` but for balance)
### StoreConfig Model
*A single document containing all global store settings.*
* `store_name` (String)
* `store_description` (String)
* `payment_methods` (Array of Objects):
* `name` (String)
* `enabled` (Boolean)
* `external_links` (Array of Objects):
* `name` (String)
* `href` (String)
* `in_nav_bar` (Boolean)
* `in_footer` (Boolean)
* `emoji_icon` (String)
* `review_reward` (Number): 0-10.
* `enforced_ratings` (Boolean)
* `announcement_bar_config` (Object):
* `enabled` (Boolean)
* `template` (Integer)
* `text` (String)
* `scrolling` (Boolean)
* `scroll_direction` (String): 'left' or 'right'.
### Blacklist Model
*Stores IPs or usernames to be blocked.*
---
## 3. API Endpoints
### Group 1: Public & Authentication
| Endpoint | Method | Description |
| ------------------------- | ------ | ---------------------------------------------- |
| `/api/public/guest/token` | `GET` | Retrieves a temporary token for a guest user. |
| `/api/auth/register` | `POST` | Registers a new user account. |
| `/api/auth/login` | `POST` | Logs in a registered user. |
### Group 2: Store & Product Discovery (Guest+)
| Endpoint | Method | Description |
| ---------------------------------- | ------ | ------------------------------------------------------------------------- |
| `/api/public/config` | `GET` | Retrieves the public-facing store configuration. |
| `/api/products/all` | `GET` | Lists all enabled products (Admins see all). |
| `/api/products/categories` | `GET` | Lists all product categories. |
| `/api/products/{productId}` | `GET` | Retrieves details for a single product. |
| `/api/products/{productId}/stock` | `GET` | Retrieves purchasable subcategories for a product. |
| `/api/subcategories/{subcategoryId}` | `GET` | Retrieves full details for a single subcategory, including parent product info. |
| `/api/reviews/all` | `GET` | Retrieves a paginated list of all reviews. |
| `/api/reviews/{productId}` | `GET` | Retrieves paginated reviews for a specific product. |
### Group 3: User Account & Cart (User/Reseller/Staff)
| Endpoint | Method | Description |
| -------------------------- | ------ | ----------------------------------------------------------------- |
| `/api/user/personal` | `GET` | Retrieves the authenticated user's profile, balance, and recent orders. |
| `/api/user/profile/update` | `PUT` | Updates the user's email or password. |
| `/api/user/cart/update` | `POST` | Adds, updates, or removes an item (`subcategoryId`) from the user's cart. |
### Group 4: Orders & Reviews (User/Reseller/Staff)
| Endpoint | Method | Description |
| ------------------------------------ | ------ | -------------------------------------------------------------------------- |
| `/api/orders/cart/checkout` | `POST` | Initiates the checkout process for the cart, returns a `redirect_url`. |
| `/api/user/balance/top-up` | `POST` | Initiates a balance top-up, returns a `redirect_url`. |
| `/api/orders/my-orders` | `GET` | Retrieves a paginated list of the user's own orders. |
| `/api/orders/{orderId}` | `GET` | Retrieves a single, detailed order owned by the user. |
| `/api/orders/{orderId}/create-review`| `POST` | Creates a review for a completed order. |
| `/api/orders/{orderId}/replace` | `POST` | Submits a replacement request for a delivered item in a completed order. |
### Group 5: Staff & Admin Endpoints
#### Staff: Replacement Management
*Accessible to `STAFF` and `ADMIN` roles.*
| Endpoint | Method | Description |
| ---------------------------------------------- | ------ | ---------------------------------------------------------- |
| `/api/staff/replacement-requests` | `GET` | Retrieves a list of all `PENDING` replacement requests. |
| `/api/staff/replacement-options/{subcategoryId}` | `GET` | Gets random, available stock items to use as replacements. |
| `/api/staff/requests/{requestId}/resolve` | `POST` | Approves or denies a specific replacement request. |
#### Admin: Full Management
*Accessible only to `ADMIN` role.*
| Endpoint | Method | Description |
| ------------------------------------------ | -------- | ------------------------------------------------------------------------- |
| `/api/admin/config` | `GET` | Retrieves the full, private store configuration. |
| `/api/admin/config/update` | `POST` | Updates any part of the store configuration. |
| `/api/admin/users` | `GET` | Retrieves a paginated list of all users. |
| `/api/admin/user/{userId}` | `GET` | Retrieves the full profile and order history for a single user. |
| `/api/admin/user/delete/{userId}` | `DELETE` | Permanently deletes a user. |
| `/api/admin/users/set_reseller/{userId}` | `GET` | Promotes a user to 'RESELLER' and sets a discount. |
| `/api/admin/product/create` | `POST` | Creates a new product. |
| `/api/admin/product/update/{productId}` | `POST` | Updates a product's details. |
| `/api/admin/product/delete/{productId}` | `DELETE` | Deletes a product and all its subcategories/stock. |
| `/api/admin/categories/create` | `POST` | Creates a new category. |
| `/api/admin/category/delete/{categoryId}` | `DELETE` | Deletes a category. |
| `/api/admin/subcategory/create` | `POST` | Creates a new subcategory for a product. |
| `/api/admin/subcategory/update/{subcategoryId}`| `POST` | Updates a subcategory's title or price. |
| `/api/admin/subcategory/delete/{subcategoryId}`| `DELETE` | Deletes a subcategory and all its stock. |
| `/api/admin/subcategory/{subcategoryId}/sync-stock`| `GET` | Recalculates and fixes the cached `stock_count` for a subcategory. |
| `/api/admin/stock/add` | `POST` | Appends new stock to a subcategory. |
| `/api/admin/stock/set` | `POST` | Overwrites all stock for a subcategory. |
| `/api/admin/stock/clear/{subcategoryId}` | `DELETE` | Clears all stock for a subcategory. |
| `/api/admin/stock/{subcategoryId}` | `GET` | Retrieves all deliverable stock items for a subcategory. |
| `/api/admin/orders` | `GET` | Retrieves a paginated list of all orders from all users. |
| `/api/admin/orders/create-and-approve` | `POST` | Creates and instantly fulfills a new order for a user (gifting). |
| `/api/admin/orders/process/{orderId}` | `POST` | Manually approves and fulfills an existing `PENDING` order. |
| `/api/admin/reviews/{reviewId}/edit` | `POST` | Edits a review's text or rating. |
| `/api/admin/reviews/{reviewId}` | `DELETE` | Deletes a review. |
| `/api/admin/stats` | `POST` | Retrieves aggregated sales data for a given timeframe and product/subcategory. |
| `/api/admin/stats/timeline` | `POST` | Retrieves time-series data points for the overview graph. |
### Group 6: Webhooks (Server-to-Server)
| Endpoint | Method | Description |
| -------------------------- | ------ | ------------------------------------------------------------------------ |
| `/api/webhooks/hoodpay` | `POST` | The public endpoint that Hoodpay sends payment status notifications to. |