Household Items API

Household Inventory

Track shared items and let PrimeCal raise restock tasks automatically

Household items are a shared inventory list, optionally scoped to a people group, with shelf-life and expiry tracking. An hourly scan creates a restock Task automatically when an item is used up or close to running out.

JWT or user API keyShelf-life trackingAutomatic restock tasksPeople-group sharing

Authentication and Permissions

• All routes on this page require authentication and the task_management plan feature (see RequireFeature('task_management')).
• Items are scoped to the authenticated owner; groupId additionally shares an item with a people group's members.

Endpoint Reference

Method	Path	Purpose	Request or query	Auth	Source
POST	/api/household-items	Create a household item.	Body: item fields	JWT or user API key	household/household-items.controller.ts
GET	/api/household-items	List items owned by the caller.	None	JWT or user API key	household/household-items.controller.ts
GET	/api/household-items/:id	Get one item.	Path: id	JWT or user API key	household/household-items.controller.ts
PATCH	/api/household-items/:id	Update an item.	Path: id, body: partial item fields	JWT or user API key	household/household-items.controller.ts
DELETE	/api/household-items/:id	Delete an item.	Path: id	JWT or user API key	household/household-items.controller.ts
POST	/api/household-items/:id/mark-used-up	Mark an item used up, which raises a restock task on the next scan (or immediately, if it already qualifies).	Path: id	JWT or user API key	household/household-items.controller.ts
POST	/api/household-items/:id/consume	Reduce quantity by an amount (default 1), e.g. "used 2 rolls of paper towels."	Path: id, body: amount (optional)	JWT or user API key	household/household-items.controller.ts

Request Shapes

Item payload

CreateHouseholdItemDto

• name: required, max 200 chars
• category: optional, max 100 chars
• quantity: optional integer, >= 0, default 1
• groupId: optional integer — shares the item with a people group
• expiryDate: optional ISO date string (YYYY-MM-DD)
• shelfLifeDays: optional integer, 1..3650
• lowStockThreshold: optional integer, >= 0 — a second, independent restock trigger for items tracked by count rather than freshness (paper towels, batteries)

UpdateHouseholdItemDto keeps the same structure but makes all fields optional.

Consume payload

ConsumeHouseholdItemDto

• amount: optional integer, >= 1, default 1

Example Calls

Create a household item with a shelf life

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Milk",
    "category": "Dairy",
    "groupId": 9,
    "shelfLifeDays": 7
  }'

List household items

curl "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN"

Mark an item used up

curl -X POST "$PRIMECAL_API/api/household-items/14/mark-used-up" \
  -H "Authorization: Bearer $TOKEN"

Track a count-based item and consume it

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paper towels",
    "category": "Cleaning",
    "quantity": 6,
    "lowStockThreshold": 2
  }'

curl -X POST "$PRIMECAL_API/api/household-items/22/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2
  }'

Response and Behavior Notes

• An hourly scan (HouseholdRestockSchedulerService) creates a Task titled Restock: <name> for any item that is isUsedUp, within 3 days of expiryDate, within 3 days of exhausting shelfLifeDays measured from lastRestockedAt, or whose quantity has dropped to or below its lowStockThreshold.
• Once an item has a pendingRestockTaskId, the scan skips it — only one open restock task exists per item at a time.
• POST /api/household-items/:id/mark-used-up sets isUsedUp: true; it does not create the restock task synchronously — the next hourly scan (or a call to the underlying scan logic) picks it up.
• POST /api/household-items/:id/consume decrements quantity by amount (clamped to zero) and sets isUsedUp: true if it reaches zero. Like mark-used-up, it never creates the restock task synchronously.
• shelfLifeDays, expiryDate, and lowStockThreshold are all independent — an item can use any combination, or none. If none are set, the item is only ever flagged via isUsedUp/consume reaching zero.

Best Practices

• Set shelfLifeDays for items you restock on a rough cycle (milk, filters, consumables) instead of tracking an exact expiryDate you'd have to update by hand.
• Set lowStockThreshold for items you track by count rather than freshness (paper towels, batteries, light bulbs) and call consume as you use them, rather than only ever marking the whole item used up at once.
• Share consumables with a groupId so the whole household — not just whoever created the item — sees it and can mark it used up or consume from it.
• Call mark-used-up/consume as soon as an item runs low rather than waiting for the shelf-life window to close on its own; it gets the restock task created sooner.