Entity Product Notes Service

Back to Entities

Overview

The Entity Product Notes module stores customer-specific instructions for individual products.

Each record captures how a particular product should be handled — customised and packed — when fulfilling an order for a specific customer. These notes override or supplement the product-level DefaultCustomisationNotes.

Examples:

• "Always embroider the logo on the left chest"
• "Pack in individual branded bags — do not bulk pack"

Notes are attached at the product level (not variant level) and apply to all variants of that product for the given entity.

All operations are tenant-aware and fully audited.

Endpoints

Back to Entities

GET

/api/v1/EntityProductNotes/entity/{entityId}/product/{productId}

Returns the notes record for a specific entity and product combination.

Route parameters:

• entityId (long, required)
• productId (long, required)

Behavior:

• Returns 404 if no record exists for this entity/product combination

Response:

• EntityProductNotesModel

Authorization:

• Requires Bearer Token
• Permission: FullRead

POST

/api/v1/EntityProductNotes

Creates or updates entity product notes (upsert).

Request body (EntityProductNotesModel):

• EntityId (long, required, must be > 0)
• ProductId (long, required, must be > 0)
• CustomisationNote (string?, optional) — instructions for customising this product for this customer
• PackingNote (string?, optional) — instructions for packing this product for this customer

Behavior:

• If a record already exists for the (EntityId, ProductId) combination, it is updated
• If no record exists, a new one is created
• EntityId and ProductId together form a unique key
• Writes an audit log entry on success

Errors:

• 422 if EntityId <= 0 or ProductId <= 0

Response:

• 200 OK — EntityProductNotesModel

Authorization:

• Requires Bearer Token
• Permission: FullManage

DELETE

/api/v1/EntityProductNotes/{id}

Deletes entity product notes by record ID.

Route parameters:

• id (long, required) — internal record identifier

Behavior:

• Hard delete
• Returns 404 if no record exists with the given ID
• Writes an audit log entry on success

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

Model

EntityProductNotesModel

• Id (type: long) — internal identifier
• EntityId (type: long) — FK to entity (customer/supplier)
• ProductId (type: long) — FK to product
• CustomisationNote (type: string?) — customisation instructions
• PackingNote (type: string?) — packing instructions

Integration with Products

When fetching products via GET /api/v1/Products with an entityId in the request, each ProductModel in the response includes a Notes field:

{
  "id": 42,
  "sku": "PROD-001",
  ...
  "notes": {
    "id": 7,
    "entityId": 5,
    "productId": 42,
    "customisationNote": "Embroider logo on left chest",
    "packingNote": "Individual branded bags"
  }
}

If no EntityProductNotes record exists for that product/entity combination, notes is null.

If the products request does not include an entityId, notes is always null.

Notes

• The (EntityId, ProductId) combination is unique — only one record per entity/product pair
• Notes apply to the product as a whole, including all its variants
• DefaultCustomisationNotes on the product is a system-wide default; EntityProductNotes is the customer-specific override
• All data is tenant-scoped