Shop It Docs
Developer ResourcescatalogProduct

Catalog Product API & Integration Guide

HTTP contracts for catalog product admin and customer/mobile endpoints.

Catalog Product - API & Integration Guide

1. How to Read / Quick Metadata

  • Module: Catalog / Product
  • Admin auth: JwtAuthGuard + RoleGuard + @Permissions(Products_*)
  • Customer/mobile auth: public endpoints (@Public())
  • Surfaces:
    • Admin: /api/admin/products
    • Customer: /api/products
    • Mobile: /api/mobile/products

Audience: Mobile/web frontend developers Scope: Product discovery, detail endpoints

2. High-Level Overview

Product APIs provide admin lifecycle management and public browse/detail surfaces for published sellable products. Product detail accepts historical slugs and resolves to the current canonical product.

3. Core Concepts and Terminology

  • Sellable visibility: customer APIs only return isSellable=true and status=published.
  • Canonical slug: current slug returned in payload.
  • Historical slug: old slug stored in product_slug_history and still resolvable.
  • Featured list endpoint: curated subset exposed by GET /products/featured.

4. Route Summary

Admin

MethodPathPermission
GET/api/admin/productsProducts_READ
GET/api/admin/products/:idProducts_READ
POST/api/admin/productsProducts_CREATE
PATCH/api/admin/products/:idProducts_UPDATE
DELETE/api/admin/products/:idProducts_DELETE

Customer + Mobile

MethodPath
GET/api/products and /api/mobile/products
GET/api/products/featured and /api/mobile/products/featured
GET/api/products/:slug and /api/mobile/products/:slug

Route Details

List Products

AspectDetails
EndpointGET /api/products or /api/mobile/products
AuthPublic
Requestpagination, search, categoryId
ResponseResponseDto<ProductDto[]>
Errors-

Product Detail

AspectDetails
EndpointGET /api/products/:slug or /api/mobile/products/:slug
AuthPublic
Request-
ResponseResponseDto<ProductDto>
Errors404 not found

5. Query Parameters

Admin list (GET /api/admin/products)

  • Inherited from QueryDto: pagination, page, size, search
  • Product filters: categoryId, productType, tagId, status, isSellable
  • Sort: title | slug | productType | mrp | sp | status | isSellable | createdAt | updatedAt | relevance
  • Order: asc | desc

Customer list (GET /api/products)

  • Inherited from QueryDto: pagination, page, size, search
  • Filters: categoryId, productType, tagId
  • Sort: title | mrp | sp | createdAt | relevance
  • Order: asc | desc
  • pagination (default true)
  • page (default 1)
  • size (defaults to env-backed CATALOG_FEATURED_DEFAULT_SIZE when omitted)

6. Response Shape Examples

Product list item

"
  "id": 101,
  "mrp": 15000,
  "sp": 12000,
  "discount": 3000,
  "categoryId": 3,
"

Product detail response example

"
  "id": 101,
  "isSellable": true,
  "categoryId": 3,
  "tags": ["" "id": 7, "name": "Hand Painted", "slug": "hand-painted" ""]
"

7. Enums

  • productStatus (admin flows): draft | published | unlisted | archived
  • productType (physical only): thangka | singing_bowl | statue | jewellery
  • Sort enums follow DTO-level allowlists (admin/customer differ).

8. Integration Diagram

9. Caching

PrefixUsage
catalog:products:list:customer list cache
catalog:product:slug:detail-by-slug cache
catalog:products:featured:customer featured list cache

Write invalidation happens on admin create/update/delete via prefix invalidation.

10. Error Handling

HTTPerrorCodeCondition
400PRODUCT_SP_EXCEEDS_MRPSelling price greater than MRP
400PRODUCT_INVALID_STATUS_TRANSITIONInvalid status transition
400PRODUCT_CREATE_FAILEDCreate returned no row
400PRODUCT_INVALID_SORTUnsupported sort field
404PRODUCT_NOT_FOUNDProduct missing
404PRODUCT_CATEGORY_NOT_FOUNDCategory ID missing
404PRODUCT_TAG_NOT_FOUNDOne or more tags missing
429RATE_LIMIT_EXCEEDEDSearch/list limiter exceeded

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

MethodPathAuth / PermissionRequest DTO / ParamsSuccess DTONotes
GET/api/admin/productsAdmin + Products_READQueryProductsAdminDto "" page?, size?, pagination?, search?, categoryId?, productType?, tagId?, status?, isSellable?, sort?, order? ""ProductAdminListItemDto[] paginatedAdmin product list with filters
GET/api/admin/products/:idAdmin + Products_READpath: id (int)ProductAdminDetailDtoAdmin product detail with history
POST/api/admin/productsAdmin + Products_CREATEbody: CreateProductDto "" title, slug, description?, shortSummary?, productType, delivery, materials, certificate, isMasterGrade, isBestSeller, size, mrp, sp, categoryId, tagIds?, thumbnailUrl?, galleryUrls?, metadata?, mainFileUrl?, previewFileUrl?, attachments?, isSellable?, ageDisclaimer?, status? ""ProductAdminDetailDtoCreates new product
PATCH/api/admin/products/:idAdmin + Products_UPDATEpath: id (int), body: UpdateProductDto "" title?, slug?, description?, shortSummary?, productType?, delivery?, materials?, certificate?, isMasterGrade?, isBestSeller?, size?, mrp?, sp?, categoryId?, tagIds?, thumbnailUrl?, galleryUrls?, metadata?, mainFileUrl?, previewFileUrl?, attachments?, isSellable?, ageDisclaimer?, status? ""ProductAdminDetailDtoUpdates product
DELETE/api/admin/products/:idAdmin + Products_DELETEpath: id (int)"" success: true ""Soft deletes product
GET/api/productsPublicQueryProductsDto "" page?, size?, pagination?, search?, categoryId?, productType?, tagId?, sort?, order? ""ProductListItemDto[] paginatedCustomer product list
GET/api/mobile/productsPublicQueryProductsDto "" page?, size?, pagination?, search?, categoryId?, productType?, tagId?, sort?, order? ""ProductListItemDto[] paginatedMobile product list (same as customer)
GET/api/products/featuredPublicQueryFeaturedProductsDto "" page?, size?, pagination? ""ProductListItemDto[] paginatedFeatured products list
GET/api/mobile/products/featuredPublicQueryFeaturedProductsDto "" page?, size?, pagination? ""ProductListItemDto[] paginatedMobile featured products
GET/api/products/:slugPublicpath: slug (string)ProductDetailDtoProduct detail by slug (supports historical slugs)
GET/api/mobile/products/:slugPublicpath: slug (string)ProductDetailDtoMobile product detail by slug

11.1.1 Admin List Endpoint Query Variations

MethodPathQuery ParametersNotes
GET/api/admin/products(no params)Default: page=1, size=20, sort=createdAt, order=desc
GET/api/admin/products?page=2&size=10Custom page and size
GET/api/admin/products?categoryId=3Filter by category
GET/api/admin/products?status=publishedFilter by status
GET/api/admin/products?isSellable=trueFilter sellable products
GET/api/admin/products?tagId=7Filter by tag
GET/api/admin/products?search=taraSearch by title/slug/description
GET/api/admin/products?sort=title&order=ascSort by title ascending
GET/api/admin/products?sort=mrp&order=descSort by MRP descending
GET/api/admin/products?status=published&isSellable=trueCombined filters

11.1.2 Customer/Mobile List Endpoint Query Variations

MethodPathQuery ParametersNotes
GET/api/products(no params)Default: page=1, size=20, sort=relevance, order=desc
GET/api/products?page=2&size=10Custom pagination
GET/api/products?categoryId=3Filter by category
GET/api/products?tagId=7Filter by tag
GET/api/products?sort=title&order=ascSort by title
GET/api/products?sort=mrp&order=descSort by MRP descending
GET/api/products?sort=sp&order=ascSort by selling price ascending
GET/api/products?sort=createdAt&order=descSort by creation date
GET/api/products?pagination=falseReturn all matching records
MethodPathQuery ParametersNotes
GET/api/products/featured(no params)Uses default size from env
GET/api/products/featured?page=1&size=10Custom page/size
GET/api/products/featured?pagination=falseAll featured products
GET/api/mobile/products/featured?size=20Mobile featured with size

11.1.4 Create Product Request Variations

MethodPathRequest BodyNotes

11.1.5 Update Product Request Variations

MethodPathRequest BodyNotes
PATCH/api/admin/products/101"" "sp": 9000 ""Update only selling price
PATCH/api/admin/products/101"" "status": "published" ""Publish product
PATCH/api/admin/products/101"" "isSellable": false ""Mark as not sellable
PATCH/api/admin/products/101"" "title": "New Title", "slug": "new-slug" ""Update title and slug
PATCH/api/admin/products/101"" "tags": [1,2,3] ""Update tags
PATCH/api/admin/products/101"" "status": "archived" ""Archive product

11.1.6 Product Status Flow States

StatusIsSellableNext Possible StatesNotes
draftfalsepublished, unlistedInitial state
publishedtrueunlisted, archivedLive on storefront
unlistedfalsepublished, archivedHidden but accessible via direct link
archivedfalse- (terminal)No longer accessible

11.1.7 Product Type Size Shapes

TypeSize ShapeNotes
thangkarectangular with inch.width, inch.height, cm.width, cm.heightCanvas/frame dimensions
singing_bowlradius with numeric inch and numeric cmSingle radius value
statueradius with numeric inch and numeric cmSingle radius value
jewellerycircumference with numeric inch and numeric cmBangle/bracelet circumference

11.1.8 Error Response Variations

HTTPerrorCodeMessageScenario
400PRODUCT_SP_EXCEEDS_MRPSelling price cannot exceed MRP.SP > MRP on create/update
400PRODUCT_INVALID_STATUS_TRANSITIONInvalid status transition.Invalid status change
400PRODUCT_CREATE_FAILEDFailed to create product.Insert returned no row
400PRODUCT_INVALID_SORTInvalid sort field.Unsupported sort value
400PRODUCT_MISSING_REQUIRED_FIELDRequired field is missing.Title, productType, delivery, materials, certificate, size, mrp, sp, categoryId
404PRODUCT_NOT_FOUNDProduct not found.Invalid product ID
404PRODUCT_CATEGORY_NOT_FOUNDCategory not found.Invalid categoryId
404PRODUCT_TAG_NOT_FOUNDOne or more tags not found.Invalid tag IDs
409PRODUCT_SLUG_EXISTSProduct with this slug already exists.Duplicate slug
429RATE_LIMIT_EXCEEDEDToo many requests.Rate limit exceeded

11.1.9 Cache Key Patterns

Cache KeyPatternTTL (seconds)Invalidation
Customer product listcatalog:products:list:pagination:"page"-size:"size"-sort:"sort"-order:"order"-filters...300Admin create/update/delete
Product detail by slugcatalog:product:slug:"slug"600Admin update/delete
Featured products listcatalog:products:featured:pagination:"page"-size:"size"300Admin create/update/delete featured
Admin product listcatalog:products:admin:list:pagination:"page"-size:"size"-filters...60Admin mutations

11.1.10 Rate Limit Patterns

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

11.1.11 DTO Field Reference

CreateProductDto

FieldTypeRequiredValidationNotes
titlestringYes1-200 charsProduct title
slugstringYes1-100 chars, URL-safeURL slug
descriptionstringNoMax 5000 charsFull description
shortSummarystringNoMax 500 charsBrief summary
deliverystringYes1-500 chars, trimmed non-emptyDelivery/shipping information
materialsstring[]YesNon-empty, unique, trimmed stringsMaterials used
certificatestringYes1-255 chars, trimmed non-emptyCertificate identifier
isMasterGradebooleanYesbooleanMaster-grade product flag
isBestSellerbooleanYesbooleanBestseller product flag
sizeobjectYesShape must match productTypePhysical size object
mrpnumberYesPositive integerMaximum retail price (paisa)
spnumberYesPositive integer, not more than mrpSelling price (paisa)
categoryIdintegerYesPositiveCategory reference
tagIdsnumber[]NoValid unique positive tag IDsTag references
thumbnailUrlstringNoValid URLThumbnail image
galleryUrlsstring[]NoValid URLsProduct gallery images
metadataobjectNoJSON objectProduct metadata
mainFileUrlstringNoValid URLMain downloadable/media file URL
previewFileUrlstringNoValid URLPreview file URL
attachmentsobject[]Noname/url/type fieldsAdditional asset attachments
isSellablebooleanNobooleanSellable visibility
ageDisclaimerstringNoMax 500 charsAge/legal disclaimer
statusenumNodraft|published|unlisted|archivedInitial status

UpdateProductDto

FieldTypeRequiredValidationNotes
titlestringNo1-200 charsProduct title
slugstringNo1-100 chars, URL-safeURL slug
descriptionstringNoMax 5000 charsFull description
shortSummarystringNoMax 500 charsBrief summary
deliverystringNo1-500 chars, trimmed non-emptyDelivery/shipping information
materialsstring[]NoNon-empty, unique, trimmed stringsMaterials used
certificatestringNo1-255 chars, trimmed non-emptyCertificate identifier
isMasterGradebooleanNobooleanMaster-grade product flag
isBestSellerbooleanNobooleanBestseller product flag
sizeobjectNoShape must match productTypePhysical size object
mrpnumberNoPositive integerMaximum retail price
spnumberNoPositive integer, < not more than mrpSelling price
categoryIdintegerNoPositiveCategory reference
tagIdsnumber[]NoValid unique positive tag IDsTag references
thumbnailUrlstringNoValid URLThumbnail image
galleryUrlsstring[]NoValid URLsProduct gallery images
metadataobjectNoJSON objectProduct metadata
mainFileUrlstringNoValid URLMain downloadable/media file URL
previewFileUrlstringNoValid URLPreview file URL
attachmentsobject[]Noname/url/type fieldsAdditional asset attachments
ageDisclaimerstringNoMax 500 charsAge/legal disclaimer
statusenumNodraft|published|unlisted|archivedProduct status
isSellablebooleanNo-Sellable flag

QueryProductsDto / QueryProductsAdminDto

FieldTypeRequiredNotes
pagenumberNoPage number (default 1)
sizenumberNoPage size (default 20, max 100)
paginationbooleanNoEnable pagination (default true)
searchstringNoSearch query
categoryIdnumberNoFilter by category
productTypeenumNoFilter by type
tagIdnumberNoFilter by tag
statusenumNo(admin only) Filter by status
isSellablebooleanNo(admin only) Filter sellable
sortstringNoSort field
orderstringNoSort order (asc/desc)

12. Testing Scenarios

12.1 Suggested Test Scenarios

  • Admin creates product with all fields, publishes it, and product appears in customer list.
  • Product slug changed in admin; old slug still resolves to canonical detail via historical slug fallback.
  • Customer list only returns isSellable=true and status=published products; draft products hidden.
  • Customer with search query "tara" returns matching products by title, shortSummary, or description.
  • Featured products endpoint returns only active slots with in-window date ranges.
  • 429 rate limit exceeded on customer list/search with sliding window Redis keys.

See Also

Featured Module Feature List

Featured placement feature contract for admin and customer/mobile catalog surfaces.

Catalog Product Backend Documentation

Backend architecture and runtime contracts for catalog product flows.

On this page

Catalog Product - API & Integration Guide1. How to Read / Quick Metadata2. High-Level Overview3. Core Concepts and Terminology4. Route SummaryAdminCustomer + MobileRoute DetailsList ProductsProduct Detail5. Query ParametersAdmin list (GET /api/admin/products)Customer list (GET /api/products)Featured list (GET /api/products/featured)6. Response Shape ExamplesProduct list itemProduct detail response example7. 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 Products Query Variations11.1.4 Create Product Request Variations11.1.5 Update Product Request Variations11.1.6 Product Status Flow States11.1.7 Product Type Size Shapes11.1.8 Error Response Variations11.1.9 Cache Key Patterns11.1.10 Rate Limit Patterns11.1.11 DTO Field ReferenceCreateProductDtoUpdateProductDtoQueryProductsDto / QueryProductsAdminDto12. Testing Scenarios12.1 Suggested Test ScenariosSee Also