Products Service

Back

Overview

Products represent sellable items in the Catalog module. They aggregate core product data together with pricing, stock and dynamic properties.

The Products service is a central integration point between:

• Catalog
• Inventory
• Pricing
• Sales

All product operations are tenant-aware and scoped to the current tenant.

Endpoints

Back to Catalog

GET

/api/v1/Products

Returns a paginated, filterable list of products for the current tenant.

Query parameters:

• page - page number (1-based, default: 1)
• pageSize - items per page (default: 20, max: 100)
• sortBy - field to sort by: sku, title, createdAt, brand, price
• sortDesc - sort descending (default: false)
• search - search across SKU, title, description
• isActive - filter by active status (true/false/null for all)
• brandId - filter by brand ID
• categoryId / categorySlug - filter by category
• supplierId - filter by supplier
• colourId / sizeId - filter by colour/size variant
• minPrice / maxPrice - price range filter
• priceListId - price list used for price filtering
• inStock - only products with stock (true/false)

Behavior:

• Returns paginated PagedResponse<ProductModel> including per product:
  • brand — full brand object { Id, Name, Code } (no separate brand request needed)
  • unitPrice — product-level base price
  • stock — product-level stock list
  • productVariants — each variant includes its own unitPrice and stock (per ProductVariantId)
  • product properties, images, SEO, dimension types
• Uses batch loading to avoid N+1 query issues

Errors:

• Returns 404 if no products exist

Authorization:

• [AllowAnonymous] — no token required

GET

/api/v1/Products/{productId}/related

Returns all related products for a given product.

Route parameters:

• productId (long, required) - product identifier

Response:

• List<ProductModel>

Authorization:

• [AllowAnonymous] — no token required

GET

/api/v1/Products/sku/{sku}

Returns a single product identified by its SKU.

Behavior:

• Looks up product by SKU
• Loads related stock and properties
• Returns 404 if product does not exist

Authorization:

• Requires Bearer Token

POST

/api/v1/Products

Creates one or more new products.

Request body:

• Array of UploadProductModel

Behavior:

• Supports bulk product creation
• Each product is validated individually
• Duplicate SKUs are skipped
• Brands are resolved by name:
  • Existing brands are reused
  • Missing brands are created automatically
  • Empty brand defaults to "Unknown brand"
• Creates:
  • Product record
  • Initial price
  • Initial stock (if provided)
  • Product properties (if provided)
• All operations are executed in a single transaction
• Successful creation writes audit log entries

Errors:

• Returns 400 if no valid products are provided

Authorization:

• Requires Bearer Token

POST

/api/v1/Products/import

Imports products from a CSV file.

Request:

• multipart/form-data
• CSV file upload

Behavior:

• Validates CSV structure and content
• Supports large files via batch processing (1000)
• Automatically splits records into:
  • new products
  • existing products (updates)
• Performs:
  • product creation
  • product updates
  • pricing updates
  • stock updates
  • property updates
• Partial failures are logged
• Import completes even if some rows are invalid

Errors:

• Returns 400 if import -
• CSV parsing errors are logged with row number

Authorization:

• Requires Bearer Token

PUT

/api/v1/Products/{id}

Updates an existing product.

Request:

• Product ID is taken from the route
• Request body is a list of UploadProductModel (single-item list is expected for ID-based update)

Behavior:

• Updates product core fields:
  • name
  • description
  • summary
  • tax code
  • active flag
• Updates pricing if UnitPrice is provided
• Updates or creates stock entries per warehouse
• Updates or creates product properties
• Changes are applied selectively (field-by-field comparison)
• All updates run inside a transaction
• Audit logs are written only if changes occur

Errors:

• Returns 400 if update - or product does not exist

Authorization:

• Requires Bearer Token

DELETE

/api/v1/Products/{id}

Deletes a product by its identifier.

Behavior:

• Performs a hard delete
• Removes:
  • product
  • stock items
  • product prices
  • product property values
• Successful deletion writes an audit log entry

Errors:

• Returns 400 if product does not exist or deletion -

Authorization:

• Requires Bearer Token

Models

ProductModel

Returned by GET endpoints.

Fields:

• Id (type: long) — internal identifier
• SKU (type: string?) — product SKU
• Title (type: string?) — product name
• Summary (type: string?) — short description
• Description (type: string?) — full description
• Brand (type: BrandModel?) — resolved brand object { Id, Name, Code }
• TaxCodeId (type: long?) — FK to tax code
• UnitOfMeasureId (type: long?) — FK to unit of measure
• WeightKg (type: decimal?) — weight in kilograms
• SupplierEntityId (type: long?) — FK to the supplier entity this product belongs to
• IsActive (type: bool) — whether the product is active
• IsRestricted (type: bool) — whether the product requires access permission
• IsStockReq (type: bool) — whether stock is required before sale
• DefaultCustomisationNotes (type: string?) — default customisation instructions for this product (applies to all customers unless overridden by Notes)
• CreatedAt (type: DateTime) — creation timestamp
• Properties (type: List<ProductPropertyItemModel>) — dynamic properties
• Images (type: List<ProductImageModel>?) — product images
• Variants (type: List<VariantResponseModel>) — product variants
• Notes (type: EntityProductNotesModel?) — customer-specific customisation and packing notes; populated only when the request includes an entityId and a matching record exists in EntityProductNotes. null if no record exists for this product/entity combination.

UploadProductModel

Used for POST (create) and PUT (update) operations.

Fields:

• Id (type: long) — required for PUT; set from route on update
• Code (type: string?) — product SKU
• Name (type: string?) — product name
• Description (type: string?) — full description
• Summary (type: string?) — short description
• IsActive (type: bool?) — active flag
• BrandId (type: long?) — FK to brand (takes precedence over Brand name if both are provided)
• Brand (type: string?) — brand name; resolved to existing brand or created automatically. Defaults to "Unknown brand" if empty
• TaxCode (type: long) — FK to tax code
• Warehouse (type: long?) — warehouse ID for initial stock
• QuantityOnHand (type: decimal?) — initial stock quantity
• ReorderLevel (type: decimal?) — reorder threshold
• QuantityAllocated (type: decimal?) — allocated quantity
• Location (type: string?) — bin/shelf location
• UnitPrice (type: decimal?) — initial product price
• ParentId (type: long) — parent product ID (0 = top-level)
• SupplierEntityId (type: long) — supplier entity FK (0 = unassigned)
• ProductProperties (type: Dictionary<string, string>) — dynamic key/value properties

Notes

• Validation is enforced in the service layer
• Product updates are transactional
• Bulk operations are optimized for large datasets
• Batch size: 1000
• Large dataset threshold: 1000
• All state-changing operations are audited
• Internal errors are logged and not exposed to clients