Favorite Listings Endpoint

[flow-pie]

Favorite Listings Endpoint

---

Describe the feature clearly

Provide an API endpoint that allows users to mark/unmark a listing as favorite and later retrieve all their saved favorites.

• Users can toggle "favorite/unfavorite" on any listing.
• A "My Favorites" section will show all bookmarked items.

---

Why is it needed

• Without a save option, user lose track and may leave the platform.
• Favorites improve user engagement, encourage repeat visits, and increase chances of conversion.

---

Issue to be solved

Currently, users cannot save listings they are interested in. This causes:

• Frustration — users must re-search items later.
• Drop-offs — they switch to screenshots or external notes.
• Lost sales — buyers forget about items they liked.

---

Any possible alternatives or similar features you’ve seen elsewhere

• OLX / Jiji → “Save Ad” button.
• Amazon → Wishlist/Favorites.
• Facebook Marketplace → Save post for later.

---

Technical Approach

Database Schema

Table: favorites
- id (PK)
- user_id (FK -> users)
- listing_id (FK -> listings)
- created_at (timestamp, default NOW())
UNIQUE(user_id, listing_id) -- no duplicates

Endpoints

1. POST /api/favorites

Add a listing to favorites.

Body

listingId (string, required)


Responses

201 — { id, listingId, createdAt }

409 — already favorited (duplicates not allowed)



2. DELETE /api/favorites/{favoriteId}

Remove a favorite by its ID.

Path

favoriteId (string, required)


Response

204 — no content


3. DELETE /api/favorites

Remove a favorite by listing reference.

Query

listingId (string, required)


Response

204 — no content


4. GET /api/favorites

Retrieve all favorites for the authenticated user.

Query

page (int, default 1)

pageSize (int, default 20, max 100)

include (string, optional) — e.g., listing to embed listing details

sort (string, optional) — createdAt:desc|asc


Response

200 — { items: [{ id, listingId, createdAt, listing? }], page, pageSize, total }



5. GET /api/favorites/exists

Check if a listing is already favorited by the user.

Query

listingId (string, required)


Response

200 — { listingId, favorited: true|false, favoriteId? }

---

Extra Features (future-proof)

Group favorites by categories (e.g., “Books”, “Electronics”, “Hostels”).

Notify users when a favorited listing drops in price or is about to expire.

Allow sharing favorite lists with friends.