Products - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin, storefront and job-facing APIs owned by the Products module, plus the tag surface owned by catalog.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Route ordering is load-bearing: literal segments (search, suggestions, bulk, import, export) are declared before :slug/:publicId routes, or the param routes swallow them (verified live: unauthenticated bulk returns 401, not 400).

5. Auth, Identity, and Permissions

Idempotency (Idempotency-Key header): create (product), restore (product-restore), bulk (product-bulk), job import (product-job-import), job export (product-job-export). Missing → 400 IDEMPOTENCY_KEY_REQUIRED; different payload same key → 409 IDEMPOTENCY_KEY_CONFLICT; in-flight → 409 IDEMPOTENCY_REQUEST_IN_PROGRESS.

6. DTO and Model Reference

6.1 CreateProductDto (body of POST /api/admin/products)

6.2 Facet PATCH DTOs

6.3 Bulk DTOs

ProductBulkIdsDto { publicIds: string[] } (non-empty, @IsUUID("7", { each: true })); ProductBulkLifecycleDto adds status; ProductBulkDiscoveryDto adds the four flags. Result: { succeeded: string[], failures: [{ publicId, errorCode }] }.

6.4 Storefront query DTOs

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/mobile/products

Purpose

The storefront listing. Called for category/brand landing pages, tag pages and filtered browsing; paginate with nextCursor.

Source Evidence

Auth and Permissions

• Auth: none — @Public()
• Guard chain: IpThrottlerGuard
• Permission: N/A
• Guest support: yes
• Rate limit: PUBLIC_READ 60/min
• Idempotency: N/A (GET)

Request

Response

200 — envelope with data (product card array), errorCode: null, nextCursor (string or null).

This route returns the card shape, not the detail shape. Every listing surface — this route, /search and /discovery/:feed — is a grid, and a grid renders a thumbnail, a name, a price, a brand and a stock badge. Sending the detail response per row shipped a gallery, videos, attachments, specifications, SEO metadata and tags for products nobody had opened, and cost six extra database reads per page plus one signed storage URL per media item rather than per product.

Every field a card does carry keeps the exact path and meaning it has on GET /:slug, so one renderer serves both — pricing.sellingPrice and media.thumbnail.url mean the same thing on either response. ProductCardShape is declared as a Pick<> over the detail shape, so renaming or removing a detail member breaks the card type at compile time — but a member added to the detail shape and never picked fails nothing, which is the one kind of drift the Pick<> tie does not catch.

The pricing block, since variants and special deals

mrp and sellingPrice are rollups — the LOWEST across the product's live, active variants. They are what every price index and every sort reads, and they are the "from Rs X" a card renders. maxSellingPrice is the upper bound, isPriceRange is maxSellingPrice > sellingPrice, and variantCount is 1 when the storefront should render no picker.

variants[] — DETAIL ONLY

GET /api/mobile/products/{slug} carries the configurations the customer may choose between, cheapest position first. A listing card does not: twenty cards times each product's variant count would multiply the hottest read in the system to populate a picker no card renders, and pricing.variantCount is the one bit a card needs — it decides between "Add to cart" and "View options".

Withdrawn and soft-deleted variants are absent, not disabled: they are no longer offered at all. Always at least one entry for a live product; an empty array means every configuration has been withdrawn and the product is unbuyable.

"variants": [
  {
    "id": "019fc692-…-00aa",
    "name": "512GB / Blue",
    "sku": "iphone-15-512-blue",
    "isDefault": false,
    "pricing": {
      "mrp": 10000000, "sellingPrice": 9000000, "effectivePrice": 8100000,
      "currency": "NPR",
      "deal": { "basePrice": 9000000, "effectivePrice": 8100000, "saving": 900000, "discountBps": 1000 }
    },
    "availability": { "inStock": true, "availableQuantity": 9 }
  }
]

All money is integer minor units (paisa), as everywhere else on this surface. A consumer divides by 100 exactly once, at its own boundary.

deal is null when no campaign covers the product, and effectivePrice then equals sellingPrice. A campaign is applied at READ time and never written to a price column, so cancelling one takes effect immediately.

Three rules, and each of them has a failure mode behind it:

1. Never total or charge from sellingPrice. It is the cheapest variant's price. On a cart line the charged figure is pricing.unitPrice, which is that line's own variant.
2. saving + effectivePrice === basePrice exactly. The backend computes the saving and subtracts it precisely so a receipt's two numbers reconstruct the original. Recomputing either from discountBps differs by a paisa at rounding boundaries.
3. Render the band as effectivePrice–deal.effectiveMaxPrice. Pairing the discounted floor with the undiscounted maxSellingPrice shows a top figure nobody is charged.

A campaign does not reorder a price-sorted listing — sorting reads the rollup, because it needs an index. A stated, accepted limitation.

For the gallery, specifications, tags, SEO, description or timestamps, read the detail route (8.4).

{
  "message": "Products fetched successfully",
  "data": [
    {
      "basic": { "id": "018f4e2a-7b3c-7c1e-9b2a-3d4e5f6a7b8f", "name": "Grey Linen Sofa", "slug": "grey-linen-sofa" },
      "pricing": {
        "mrp": 100000, "sellingPrice": 80000, "maxSellingPrice": 120000,
        "isPriceRange": true, "variantCount": 3,
        "discount": 20000, "discountPercentage": 20, "currency": "NPR",
        "effectivePrice": 64000,
        "deal": { "basePrice": 80000, "effectivePrice": 64000, "saving": 16000, "discountBps": 2000, "effectiveMaxPrice": 96000 }
      },
      "classification": { "brand": { "publicId": "018f4e2a-…", "name": "Acme Furniture", "slug": "acme-furniture" } },
      "media": { "thumbnail": { "url": "/public/sofa.jpg", "alt": "a grey sofa", "expiresAt": null } },
      "status": { "lifecycle": "published", "saleStatus": "on_sale", "stockStatus": "in_stock", "purchasable": true },
      "inventory": { "stockStatus": "low_stock", "isLowStock": true, "isOutOfStock": false, "isTracked": true, "available": 3 }
    }
  ],
  "errorCode": null,
  "nextCursor": "eyJzb3J0IjoibmV3ZXN0IiwidmFsdWUiOiIxNzQ2..."
}

Notes on the fields that are easy to misread:

• status.purchasable is the single owner of "can this be bought". Do not re-derive it from inventory — that answers how many there are, which is a different question, and is null for a product with no inventory row.
• classification.brand is the only classification a card carries, and it is null for a product with no brand. Category, brand series and tags are detail-response fields.
• status.visibility is absent — it is derived from lifecycle, and a listing only ever emits published rows.
• rating is absent, deliberately. A rating per card is a join per page. Ask the Reviews module for the summaries a page needs in one call.
• media.thumbnail falls back to the lowest-order gallery image when the product has no explicit thumbnail. The rest of the gallery is neither included nor signed.

Side Effects

None — read-only; Redis cache on the resolved key.

Error Cases

Example Requests

GET /api/mobile/products?categorySlug=sofas&tags=best-seller&sort=priceAsc&limit=20 HTTP/1.1

8.2 GET /api/mobile/products/search

Same contract as 8.1 — including the card shape — plus sort=relevance; term < 2 chars is treated as no search. Rate limit PUBLIC_SEARCH 60/min. Ranking is similarity(name, term) DESC, id DESC.

8.3 GET /api/mobile/products/suggestions

200 with at most 10 items { entityType-less: publicId, name, slug }; no pagination. Rate limit PUBLIC_SUGGEST 300/min.

8.4 GET /api/mobile/products/:slug

Purpose

Product detail. Accepts a current or retired slug; unlisted products resolve here only.

Auth and Permissions

@Public(), PUBLIC_READ 60/min.

Response

200 — single grouped product, the full detail shape (customer surface: no version, no metadata). basic.slug is always the current slug.

This is the only storefront product route that returns the detail shape, and deliberately so: a product page renders the gallery, the specifications and the SEO block. It also carries rating and canonicalSlug, neither of which appears on a listing.

Error Cases

Edge Cases

Retired slug → 200 with current slug (frontend redirects; API does not 3xx). Hidden/deleted → 404. unlisted → 200 here, absent everywhere else.

8.5 GET /api/mobile/products/discovery/:feed

feed in featured | trending | best-seller | new-arrival | on-sale. 200 with cursor-paginated items in the same card shape as 8.1; rate limit PUBLIC_HIGH_FREQUENCY 300/min. Unknown feed → 400 PRODUCT_INVALID_DISCOVERY_FEED. The feed itself is the filter — only cursor/limit query params.

The discovery flags themselves are not on the response. The feed you called already says which one is set, and no grid renders the other three.

8.6 POST /api/admin/products

Purpose

Create a product as draft with an inventory row, slug and SEO link in one transaction.

Auth and Permissions

• Auth: bearer token
• Guard chain: JwtAuthGuard, RoleGuard, IpThrottlerGuard
• Permission: Products_CREATE
• Rate limit: ADMIN_WRITE 10/min
• Idempotency: Idempotency-Key (scope product)

Request

Body per §6.1 (minimal: { "name", "categoryPublicId", "mrp", "sellingPrice" }).

Response

201 — envelope with the grouped product (admin surface: version, metadata).

Side Effects

product + product_slug + inventory (untracked) + optional seo rows in one transaction; activity record; cache invalidation (product/tag/inventory domains).

Error Cases

8.7 PATCH /api/admin/products/:publicId

General update; cannot change lifecycle/stock/pricing/media/seo/discovery/tags (each has its own endpoint). 409 PRODUCT_VERSION_CONFLICT on stale version; 409 PRODUCT_ALREADY_DELETED on a deleted row; 409 PRODUCT_ARCHIVED_NOT_EDITABLE while archived. 200 with grouped response.

8.8 PATCH /api/admin/products/:publicId/lifecycle

See Features and flows §7. Errors: 409 PRODUCT_INVALID_STATUS_TRANSITION, PRODUCT_THUMBNAIL_REQUIRED_TO_PUBLISH, PRODUCT_ARCHIVED_NOT_EDITABLE, PRODUCT_VERSION_CONFLICT. Side effects: product.status, seo.robots_index, activity, cache.

8.9 PATCH /api/admin/products/:publicId/stock

Purpose

Set the product stock status. Narrowed for tracked products — the column belongs to inventory once tracking is on.

Request

{ "stockStatus": "in_stock", "version": 3 }

Error Cases

Leaving pre_order on a tracked product re-derives the status from inventory counters; untracked products keep the unrestricted set.

8.10 PATCH /:publicId/{pricing,media,seo,discovery,tags}

Same envelope, permission and rate limit as the general PATCH; payloads per §6.2. Side effects: row update + version bump + activity + cache invalidation. Errors: 409 PRODUCT_VERSION_CONFLICT, PRODUCT_ARCHIVED_NOT_EDITABLE, PRODUCT_ALREADY_DELETED, media caps (PRODUCT_GALLERY_LIMIT_EXCEEDED 30, PRODUCT_ATTACHMENT_LIMIT_EXCEEDED 20, PRODUCT_VIDEO_LIMIT_EXCEEDED 10), PRODUCT_TAG_NOT_FOUND, PRODUCT_TAG_LIMIT_EXCEEDED (25).

8.11 DELETE /api/admin/products/:publicId

200 message-only body ({ message, errorCode }, no data). 404 PRODUCT_NOT_FOUND; 409 PRODUCT_ALREADY_DELETED. Soft delete only — hard delete is structurally unsupported (product_slug RESTRICT).

8.12 POST /api/admin/products/:publicId/restore

200 with grouped response. 409 PRODUCT_NOT_DELETED. Idempotency-Key (scope product-restore).

8.13 POST /api/admin/products/bulk/*

Four bulk routes; 200 with { succeeded, failures }; cap 100 unique ids (409 PRODUCT_BULK_LIMIT_EXCEEDED); rate limit ADMIN_BULK_WRITE 5/min; Idempotency-Key (scope product-bulk). Bulk delete/restore guard per item (PRODUCT_NOT_FOUND, PRODUCT_ALREADY_DELETED, PRODUCT_NOT_DELETED); bulk lifecycle validates each transition; bulk discovery sets the four flags.

8.14 POST /api/admin/products/jobs/import

multipart/form-data (file + entity). Requires Products_CREATE at the route and Products_CREATE + Products_UPDATE in the service. Idempotency-Key (scope product-job-import); rate limit ADMIN_ASYNC_JOB_SUBMIT 10/hour. Errors: 400 PRODUCT_IMPORT_FILE_INVALID / PRODUCT_IMPORT_FILE_TOO_LARGE / IDEMPOTENCY_KEY_REQUIRED; 403 PRODUCT_JOB_ENTITY_PERMISSION_DENIED / PERMISSION_ROLE_NOT_ASSIGNED; 409 idempotency conflicts. Returns 200 with the queued job.

8.15 POST /api/admin/products/jobs/export

JSON body { entity, includeDeleted?, search? }. Permission Products_READ; Idempotency-Key (scope product-job-export). Returns the queued job; a filter set matching > 50,000 rows fails the job (PRODUCT_EXPORT_TOO_LARGE).

8.16 POST /api/admin/products/jobs/:publicId/cancel

200 with the job row; 404 PRODUCT_JOB_NOT_FOUND; 409 PRODUCT_JOB_NOT_CANCELLABLE from a terminal state. Cooperative — a processing import aborts and rolls back.

8.17 GET /api/admin/products/jobs(/:publicId)

List (paginated, filters kind/entity/status, ordered by createdAt) and detail (adds startedAt, isStalled, retained errors). Permission Products_READ, ADMIN_READ 30/min.

8.18 GET /api/admin/products/jobs/import-template

Downloads the column template for an import file — header row only, no example row, because a downloadable import file is eventually uploaded unmodified and a data row would create junk. Zero rows is a no-op.

entity is product — required even though it is the only value, so the three template routes read alike.

Permission Products_READ — the file carries no data, only column names. Rate limit ADMIN_READ 30/min. Returns 200 as text/csv; charset=utf-8 with Content-Disposition: attachment. An unknown entity fails DTO validation with 400.

Columns: sku, name, categoryPublicId, brandPublicId, brandSeriesPublicId, mrp, sellingPrice, shortDescription, description. The classification columns are publicIds, unlike catalog import which links by slug.

The list is generated from the same constant the row builder's fields are typed against, so a column cannot silently diverge from what the parser reads: satisfies rejects a column that is not a row field, an Exclude assertion rejects a row field with no column, and a round-trip spec parses the emitted template back through the real builder.

Route ordering is load-bearing — this literal segment is declared above @Get(":publicId") in the controller. Declared after it, the wildcard swallows the path and the request fails as "publicId must be a UUID".

8.19 Tag endpoints (/api/admin/catalog/tags, /api/mobile/catalog/tags)

Admin: list/detail/create(201)/update/visibility/delete(200 message-only)/restore(200). Permissions Tags_*, rate limits ADMIN_READ/ADMIN_WRITE. Errors: 404 TAG_NOT_FOUND; 409 TAG_SLUG_ALREADY_EXISTS, TAG_ALREADY_DELETED, TAG_NOT_DELETED, TAG_HAS_LINKED_PRODUCTS (delete while linked). Storefront: GET /api/mobile/catalog/tags (visible tags), GET /:slug (404 TAG_NOT_FOUND), PUBLIC_READ 60/min.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (admin mutation)

9.3 Error Branch (lifecycle)

10. Pagination, Sorting, Filtering, and Search

Cursor behavior: opaque; sort-bound (400 PAGINATION_CURSOR_INVALID on mismatch); nextCursor: null = last page; over-fetch +1 instead of COUNT.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered in §8: minimal + full create payloads (§6.1/8.6), success responses (§8.1, 8.4), empty-list behavior (data: [], nextCursor: null), validation error (400 IDEMPOTENCY_KEY_REQUIRED representative), domain errors per endpoint (§8 error tables), rate-limit behavior (throttler 429 on exceeding per-surface limits), admin permission errors (403).

13.3 API Diagram Pack

Route ownership (§9.1), sequence per endpoint family (§9.2, backend §7), activity diagrams per mutation family (§9.3, features §6), error decision trees (§9.3), data contract map (backend §5.3 ER + §6 service tables), async/job flow (backend §7.3 import sequence), cache flow (backend §11).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8, §13.1).
• Every parent route prefix and runtime URL is documented (§2, §4).
• Every DTO field, enum, default, transform and validator is documented (§6, §7).
• Every response field, nullable field, generated field and omitted raw entity field is documented (§8.1, backend §5.2).
• Every auth, guard, permission, public decorator and guest identity branch is documented (§5).
• Every success, validation, auth, permission, not-found, conflict, rate-limit and server-error branch is documented (§8 error tables).
• Every DB read/write, cache hit/miss/invalidation, queue job, audit log and external call is documented (§11, backend §9/§10/§11).
• Every route has examples for minimal request, success response and representative failures (§8).
• Every endpoint family has route, sequence, activity and error diagrams (§9, backend §7).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows (§1, See Also).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission is documented.
• Every cache key, queue job and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

Variants

Since the variant migration, price, SKU and stock live on the variant, not on the product. product.mrp and product.selling_price are trigger-maintained rollups over the product's live, active variants, and inventory, cart_item, checkout_session_item, order_item and pos_sale_item all key on variant_id.

Permissions reuse Products_* deliberately. A separate Variants_* set would create roles that can edit a product but not its price, which is not a role anybody wants.

Rules

• Every product has at least one variant, and exactly one is the default. Deleting the last live one is refused.
• Writing a variant's price moves the product's rollup, because a statement-level trigger recomputes selling_price, mrp, max_selling_price and variant_count from the variants. The admin UI must re-read the product after a variant write rather than assuming its price fields are unchanged.
• Writes are optimistically locked on version. Send the version you read.
• A variant carries exactly one value per option axis the product declares, and no two variants of a product may share a combination. Both are enforced by the database.
• Repricing the PRODUCT row directly is meaningless — it is derived, and the next variant write overwrites it.

Error codes

Media

Each variant carries its own thumbnailKey, thumbnailAlt and ordered gallery[] — never shared with the product's own gallery, though the two use the identical element shape ({key, alt, order}) so the storefront can compose them into one slide strip.

CreateProductVariantDto / UpdateProductVariantDto accept thumbnailKey (storage key, IsStorageKey), thumbnailAlt and gallery[] (ProductVariantGalleryItemDto[], capped at MAX_VARIANT_GALLERY_ITEMS = 20 — lower than the product's 30 because it is read on every product-detail request for every live variant). The gallery editor always sends the field explicitly: omitting gallery leaves the stored gallery untouched; sending [] clears it.

Admin response (ProductVariantResponseDto) carries both the raw key and the resolved URL — thumbnailKey / thumbnailUrl, and each gallery item's key / url — because an operator legitimately previews objects that are not yet public. The customer response never does this; see below.

Customer contract — variants[].media on GET /api/mobile/products/{slug}:

{
  thumbnail: { url: string; alt: string | null } | null;
  gallery: { url: string; alt: string | null; order: number }[];
}

Resolution order (shared with the product-level rule, not a second implementation): the variant's own thumbnailKey, trimmed, when non-empty; else the gallery entry with the lowest order (ties broken by array position); else null. thumbnail: null with an empty gallery is the normal case — "this variant adds no media of its own" — and the storefront falls back to the product's thumbnail, never a placeholder. An unresolvable key is dropped from the gallery and never emitted as { url: "" }, which is truthy and would defeat a caller's if (media.thumbnail) check. See Backend §5.4 for the full rule and why the trim is required.

Related products

GET /api/products/related/{slug}

Public, also served under /api/mobile. Cached, cursor-paginated, and returns the same card shape as every other listing.

It reuses ProductStorefrontQueryService rather than running its own query, and that is the whole design: it guarantees the identical published/not-deleted predicate, the identical keyset pagination, the identical card shape and the identical price rollups as GET /products. A hand-rolled query here would be a second place for the storefront's visibility rules to drift.

Products are related by sharing the subject's category or subcategory. The subject itself is excluded.

See Also

• Backend doc: /docs/developer/products/backend
• Features and flows doc: /docs/developer/products/feature
• TDD: not yet published