Shop It Docs
Developer ResourcescatalogFeatured

Featured Module API & Integration Guide

HTTP contract reference for catalog featured admin and customer/mobile APIs.

Audience: Mobile/web frontend developers Scope: Featured content endpoints

1. How to Read / Quick Metadata

  • Module: Catalog / Featured
  • Admin auth: JwtAuthGuard + RoleGuard + @Permissions(Featured_*)
  • Customer/mobile auth: public endpoint (@Public())
  • Surfaces:
    • Admin: /api/admin/featured
    • Customer: /api/featured
    • Mobile: /api/mobile/featured

2. High-Level Overview

Featured APIs allow admins to manage campaign slots tied to products and let public clients fetch active, in-window featured records.

3. Core Concepts and Terminology

  • Featured row: one placement slot with title, linked productId, optional categoryId, and ordering.
  • Active-window filtering: customer responses require active flag + current-time date-window match.
  • Date window invariant: startDate not more than endDate when both values are set.

4. Route Summary

MethodPathPermission
GET/api/admin/featuredFeatured_READ
GET/api/admin/featured/:idFeatured_READ
POST/api/admin/featuredFeatured_CREATE
PATCH/api/admin/featured/:idFeatured_UPDATE
DELETE/api/admin/featured/:idFeatured_DELETE
GET/api/featured and /api/mobile/featuredPublic

Route Details

AspectDetails
EndpointGET /api/featured or /api/mobile/featured
AuthPublic
RequestisActive filter
ResponseResponseDto<FeaturedDto[]>
Errors-

5. Query Parameters

Admin list (GET /api/admin/featured)

  • Inherited from QueryDto: pagination, page, size, search
  • Filters: categoryId, isActive
  • Sort: title | order | isActive | startDate | endDate | createdAt | updatedAt
  • Order: asc | desc

Customer list (GET /api/featured)

  • Inherited from QueryDto: page, size, search
  • Defaults: pagination=false, sort=order, order=asc, isActive=true
  • Filters: categoryId, optional isActive override
  • Sort: order | createdAt

6. Response Shape Examples

"
  "id": 301,
  "title": "Top Picks This Week",
  "description": "Campaign slot for high-converting products this week.",
  "productId": 101,
  "categoryId": 3,
  "order": 0,
  "isActive": true,
  "startDate": "2026-02-21T00:00:00.000Z",
  "endDate": "2026-03-21T23:59:59.999Z"
"

Create payload

"
  "title": "Top Picks This Week",
  "productId": 101,
  "categoryId": 3,
  "order": 0,
  "isActive": true
"

7. Enums

No module-specific DB enum is used for featured DTOs. Relevant constrained values come from DTO allowlists:

  • admin sort: title | order | isActive | startDate | endDate | createdAt | updatedAt
  • customer sort: order | createdAt
  • order: asc | desc

8. Integration Diagram

9. Caching

PrefixUsage
catalog:featured:list:customer featured list cache

Admin write operations invalidate catalog:featured:active* and catalog:featured:list:*.

10. Error Handling

HTTPerrorCodeCondition
400FEATURED_INVALID_DATE_RANGEstartDate is after endDate
400CATEGORY_NOT_FOUNDProvided categoryId does not exist
400FEATURED_INVALID_SORTUnsupported customer sort field
404FEATURED_NOT_FOUNDFeatured row not found

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

MethodPathAuth / PermissionRequest DTO / ParamsSuccess DTONotes
GET/api/admin/featuredAdmin + Featured_READQueryFeaturedAdminDto "" page?, size?, pagination?, search?, categoryId?, isActive?, sort?, order? ""FeaturedAdminListItemDto[] paginatedAdmin featured list
GET/api/admin/featured/:idAdmin + Featured_READpath: id (int)FeaturedAdminDetailDtoAdmin featured detail
POST/api/admin/featuredAdmin + Featured_CREATEbody: CreateFeaturedDto "" title, description?, productId, categoryId?, order?, isActive?, startDate?, endDate? ""FeaturedAdminDetailDtoCreates new featured slot
PATCH/api/admin/featured/:idAdmin + Featured_UPDATEpath: id (int), body: UpdateFeaturedDto "" title?, description?, productId?, categoryId?, order?, isActive?, startDate?, endDate? ""FeaturedAdminDetailDtoUpdates featured slot
DELETE/api/admin/featured/:idAdmin + Featured_DELETEpath: id (int)"" success: true ""Deletes featured slot
GET/api/featuredPublicQueryFeaturedDto "" page?, size?, isActive?, categoryId?, sort?, order? ""FeaturedResponseDto[]Customer featured list
GET/api/mobile/featuredPublicQueryFeaturedDto "" page?, size?, isActive?, categoryId?, sort?, order? ""FeaturedResponseDto[]Mobile featured list

11.1.1 Admin List Endpoint Query Variations

MethodPathQuery ParametersNotes
GET/api/admin/featured(no params)Default: page=1, size=20, sort=createdAt, order=desc
GET/api/admin/featured?page=2&size=10Custom page and size
GET/api/admin/featured?search=promoSearch by title
GET/api/admin/featured?categoryId=3Filter by category
GET/api/admin/featured?isActive=trueActive featured only
GET/api/admin/featured?isActive=falseInactive featured only
GET/api/admin/featured?sort=title&order=ascSort by title
GET/api/admin/featured?sort=order&order=ascSort by order
GET/api/admin/featured?sort=startDate&order=ascSort by start date
GET/api/admin/featured?sort=endDate&order=descSort by end date descending

11.1.2 Customer/Mobile List Endpoint Query Variations

MethodPathQuery ParametersNotes
GET/api/featured(no params)Default: no pagination, sort=order, order=asc, isActive=true
GET/api/featured?page=1&size=10Paginated request
GET/api/featured?isActive=trueExplicit active filter
GET/api/featured?isActive=falseInactive items
GET/api/featured?categoryId=3Filter by category
GET/api/featured?sort=order&order=ascSort by display order
GET/api/featured?sort=createdAt&order=descSort by creation date
GET/api/mobile/featured?categoryId=1&isActive=trueMobile: active items in category
ScenariostartDateendDateisActiveResult
Currently active2026-01-012026-12-31trueReturned in customer list
Future start2026-06-012026-12-31trueNot returned (not in window)
Past end2026-01-012026-03-01trueNot returned (window expired)
InactiveanyanyfalseNot returned (filtered)
No dates (always active)nullnulltrueReturned if isActive=true
MethodPathRequest BodyNotes
POST/api/admin/featured"" "title": "Top Picks", "productId": 101 ""Minimal create
POST/api/admin/featured"" "title": "Summer Sale", "productId": 101, "categoryId": 3, "isActive": true ""With category and active
POST/api/admin/featured"" "title": "Weekend Deal", "productId": 102, "order": 0 ""With order
POST/api/admin/featured"" "title": "Limited Time", "productId": 103, "startDate": "2026-04-01", "endDate": "2026-04-07" ""With date window
POST/api/admin/featured"" "title": "Featured Thangka", "productId": 104, "description": "Highlighted this month" ""With description
MethodPathRequest BodyNotes
PATCH/api/admin/featured/1"" "title": "New Title" ""Update title only
PATCH/api/admin/featured/1"" "productId": 102 ""Change linked product
PATCH/api/admin/featured/1"" "isActive": false ""Deactivate featured slot
PATCH/api/admin/featured/1"" "order": 5 ""Update display order
PATCH/api/admin/featured/1"" "startDate": "2026-05-01", "endDate": "2026-05-31" ""Update date window
PATCH/api/admin/featured/1"" "categoryId": null ""Remove category filter
ScenarioConstraintError
startDate > endDateStart date after end dateFEATURED_INVALID_DATE_RANGE
Both required for windowIf startDate set, endDate must be set-
Category must existcategoryId must reference valid categoryCATEGORY_NOT_FOUND

11.1.7 Error Response Variations

HTTPerrorCodeMessageScenario
400FEATURED_INVALID_DATE_RANGEStart date must be before end date.startDate > endDate
400CATEGORY_NOT_FOUNDCategory not found.Invalid categoryId
400FEATURED_INVALID_SORTInvalid sort field.Unsupported sort
404FEATURED_NOT_FOUNDFeatured not found.Invalid ID

11.1.8 Cache Key Patterns

Cache KeyPatternTTL (seconds)Invalidation
Customer featured listcatalog:featured:list:isActive:"isActive"-categoryId:"categoryId"-sort:"sort"-order:"order"300Admin create/update/delete
Admin featured listcatalog:featured:admin:list:pagination:"page"-size:"size"-filters...60Admin mutations

11.1.9 Rate Limit Patterns

Route FamilyKey PatternLimit
Customer listrl:catalog:featured:customer:list-ip:"ip"60 req/min
Admin listrl:catalog:featured:admin:list-key:"adminId"60 req/min
Admin mutationsrl:catalog:featured:admin:mutate-key:"adminId"30 req/min

11.1.10 DTO Field Reference

CreateFeaturedDto

FieldTypeRequiredValidationNotes
titlestringYes1-200 charsFeatured slot title
descriptionstringNoMax 500 charsDescription text
productIdintegerYesPositive integerLinked product ID
categoryIdnumberNoPositive integerOptional category filter
ordernumberNoInteger, default 0Display order
isActivebooleanNoDefault trueActive flag
startDatestringNoISO 8601 dateWindow start date
endDatestringNoISO 8601 dateWindow end date

UpdateFeaturedDto

FieldTypeRequiredValidationNotes
titlestringNo1-200 charsFeatured slot title
descriptionstringNoMax 500 charsDescription text
productIdnumberNoPositive integerLinked product ID
categoryIdnumberNoPositive integerOptional category filter
ordernumberNoIntegerDisplay order
isActivebooleanNo-Active flag
startDatestringNoISO 8601 dateWindow start date
endDatestringNoISO 8601 dateWindow end date

QueryFeaturedDto / QueryFeaturedAdminDto

FieldTypeRequiredNotes
pagenumberNoPage number
sizenumberNoPage size
paginationbooleanNo(admin only) Enable pagination
searchstringNo(admin only) Search query
categoryIdnumberNoFilter by category
isActivebooleanNoFilter by active status
sortstringNoSort field
orderstringNoSort order

12. Testing Scenarios

12.1 Suggested Test Scenarios

  • Admin creates featured slot with future startDate; not returned in customer list (outside window).
  • Admin creates featured slot with past endDate; not returned in customer list (window expired).
  • Featured slot with both dates set and current time within window; returned in customer list.
  • Customer list returns only isActive=true records; inactive slots filtered out.
  • Admin attempts to create featured with startDate after endDate; receives 400 FEATURED_INVALID_DATE_RANGE.
  • Featured endpoint filtered by categoryId; returns only matching category slots.

See Also

Tag Module Feature List

Tag feature contract for admin and customer/mobile catalog surfaces.

Featured Module Backend Documentation

Backend architecture and runtime contracts for catalog featured flows.

On this page

1. How to Read / Quick Metadata2. High-Level Overview3. Core Concepts and Terminology4. Route SummaryRoute DetailsList Featured5. Query ParametersAdmin list (GET /api/admin/featured)Customer list (GET /api/featured)6. Response Shape ExamplesFeatured response itemCreate payload7. Enums8. Integration Diagram9. Caching10. Error Handling11. Endpoint Reference + Payload Cheatsheet11.1 Payload Cheatsheet Table (Every Endpoint)11.1.1 Admin List Endpoint Query Variations11.1.2 Customer/Mobile List Endpoint Query Variations11.1.3 Featured Active Window Filtering11.1.4 Create Featured Request Variations11.1.5 Update Featured Request Variations11.1.6 Featured Date Range Constraints11.1.7 Error Response Variations11.1.8 Cache Key Patterns11.1.9 Rate Limit Patterns11.1.10 DTO Field ReferenceCreateFeaturedDtoUpdateFeaturedDtoQueryFeaturedDto / QueryFeaturedAdminDto12. Testing Scenarios12.1 Suggested Test ScenariosSee Also