Promotions: Events & Coupons
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The promotions system is a core feature of the e-commerce platform, designed to enable sellers to drive sales and attract customers through special offers. It is comprised of two distinct but complementary functionalities: Events and Coupons.
Events are time-sensitive promotional campaigns where specific products are offered at a discounted price for a limited period. This allows sellers to create flash sales or seasonal offers. Coupons are discount codes that sellers can create and manage. Customers can apply these codes during the checkout process to receive a percentage-based discount on their purchase from a specific shop. This dual system provides sellers with flexible tools to manage their marketing and pricing strategies.
Sources: README.md, frontend/src/components/Shop/CreateEvent.jsx, frontend/src/components/Shop/AllCoupons.jsx
Events
Events are time-bound sales on products, managed by sellers through their dashboard.
Event Data Model
An Event is essentially a product with additional time-based properties. The data for an event is captured through the "Create Event" form in the seller's dashboard.
| Field | Type | Description | Source File |
|---|---|---|---|
name | String | The name of the event/product. | CreateEvent.jsx:110 |
description | String | Detailed description of the event/product. | CreateEvent.jsx:121 |
category | String | The product category. | CreateEvent.jsx:132 |
tags | String | Optional tags for discoverability. | CreateEvent.jsx:96 |
originalPrice | Number | The original price of the product. | CreateEvent.jsx:150 |
discountPrice | Number | The promotional price for the event. | CreateEvent.jsx:159 |
stock | Number | The quantity of the product available for the event. | CreateEvent.jsx:168 |
shopId | String | The ID of the seller's shop creating the event. | CreateEvent.jsx:99 |
start_Date | Date | The start date of the promotional event. | CreateEvent.jsx:100 |
Finish_Date | Date | The end date of the promotional event. | CreateEvent.jsx:101 |
images | File[] | An array of images for the event product. | CreateEvent.jsx:89 |
Sources: frontend/src/components/Shop/CreateEvent.jsx:15-25, 88-102
Backend API for Events
The backend provides endpoints under the /api/v2/event route to manage events. These endpoints handle the creation, retrieval, and deletion of events.
| Method | Endpoint | Description | Source File |
|---|---|---|---|
POST | /create-event | Creates a new event. Authenticated for sellers. | CreateEvent.jsx:102 |
GET | /get-all-events-shop/:id | Retrieves all events for a specific shop. | (Inferred from seller dashboard functionality) |
GET | /get-all-events | Retrieves all active events for customers. | data.js:10 (EVENTS nav link) |
DELETE | /delete-shop-event/:id | Deletes an event. Authenticated for sellers. | (Inferred from seller dashboard functionality) |
Sources: backend/app.js:68, frontend/src/components/Shop/CreateEvent.jsx:102
Event Creation Flow
Sellers create events through their dashboard. The process involves filling out a form, which is then submitted to the backend for processing.
The diagram below illustrates the sequence of creating a new event.
Displaying Events to Customers
Events are displayed to customers throughout the site, often using a card format similar to regular products but potentially with a special designation. The ProductCard component can render an event by passing an isEvent={true} prop. This modifies the link to the product details page to include an event identifier.
// Example of a link for an event product
<Link
to={`${
isEvent === true
? `/product/${data.id}?isEvent=true`
: `/product/${data.id}`
}`}
>
Sources: frontend/src/components/Route/ProductCard/ProductCard.jsx:70-76
Coupons
Coupons are discount codes managed by sellers and applied by customers at checkout.
Coupon Data Model
A coupon is defined by its name, discount value, and optional conditions like minimum/maximum purchase amounts.
| Field | Type | Description | Source File |
|---|---|---|---|
name | String | The unique coupon code (e.g., "SUMMER10"). | AllCoupons.jsx:136 |
value | Number | The percentage discount value. | AllCoupons.jsx:147 |
minAmount | Number | Optional minimum order value to apply the coupon. | AllCoupons.jsx:158 |
maxAmount | Number | Optional maximum order value for the coupon. | AllCoupons.jsx:169 |
selectedProducts | String | Optional specific product the coupon applies to. | AllCoupons.jsx:180 |
shopId | String | The ID of the shop that owns the coupon. | AllCoupons.jsx:62 |
Sources: frontend/src/components/Shop/AllCoupons.jsx:16-23, 58-65
Backend API for Coupons
The backend exposes endpoints under /api/v2/coupon for all coupon-related operations.
| Method | Endpoint | Description | Source File |
|---|---|---|---|
POST | /create-coupon-code | Creates a new coupon code. Authenticated for sellers. | AllCoupons.jsx:56-66 |
GET | /get-coupon/:shopId | Retrieves all coupon codes for a specific shop. | AllCoupons.jsx:38-40 |
GET | /get-coupon-value/:name | Retrieves and validates a coupon by its name for a customer. | Checkout.jsx:65 |
DELETE | /delete-coupon/:id | Deletes a coupon code. Authenticated for sellers. | AllCoupons.jsx:49 |
Sources: backend/app.js:69, frontend/src/components/Shop/AllCoupons.jsx, frontend/src/components/Checkout/Checkout.jsx
Coupon Management Flow (Seller)
Sellers manage their coupons from a dedicated section in their dashboard. They can view existing coupons in a data grid and create new ones via a modal form.
This diagram shows the flow for a seller creating a new coupon.
Coupon Application Flow (Customer)
Customers can apply a coupon code on the checkout page to receive a discount.
The following diagram illustrates the process of a customer applying a coupon.
The validation logic in the Checkout.jsx component first verifies the coupon's existence via an API call. If the coupon exists, it then checks if the coupon's shopId matches the shopId of any items in the cart. If both checks pass, the discount is calculated as a percentage of the total price of eligible items and applied to the final order total.
Sources: frontend/src/components/Checkout/Checkout.jsx:68-78
Summary
The Promotions module is a powerful, two-pronged system that enhances the platform's commercial capabilities. Events provide a mechanism for time-limited product sales, managed entirely by sellers. Coupons offer a flexible discount system where sellers can create codes that customers apply at checkout for store-specific savings. Together, these features provide essential marketing tools for sellers and value for customers, driving engagement and sales across the platform.