Add Supply Delivery and Inventory docs for 3.1

versioned_docs/version-3.1/concepts/supply/inventory-item.mdx

@@ -1,69 +1,51 @@
 ---
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 # Inventory Item
 
-An **inventory item** is the live stock count of one product at one place in your facility — how many units of a specific medicine, consumable, or device are on hand in a particular store, ward, or pharmacy right now. It is the answer to the everyday question "do we have it, and how much?"
+## Definition
 
-## What it represents
+An **[inventory item](https://build.fhir.org/inventoryitem.html)** in Care shows how much of one stocked batch is in stock at one location. Care calculates this count for you. You cannot create or edit an inventory item, and there is no manual stock adjustment.
 
-In Care's FHIR-aligned model, an inventory item maps to the **InventoryItem** resource. Each row captures:
+## Key Attributes
 
-- **What** — the product being counted (a specific medicine, consumable, or supply)
-- **Where** — the single facility location that holds that stock (central store, ward pharmacy, OT cupboard)
-- **How much** — the current on-hand quantity, kept up to date by the system
-- **Availability** — whether the line is live, retired, or recorded in error
+| Components | What it captures |
+| --- | --- |
+| Product | The specific stocked batch that this count is for. |
+| Net Content | The quantity that is in stock now. |
+| Status | The current state of the inventory item. |
+| Expiration Date | The date after which you cannot use the batch. |
+| Batch/Lot Number | The batch or lot number of the stocked product. |
+| Purchase/Base Price | The purchase price or base price of the stocked product. |
 
-An inventory item is not a catalogue entry and not a single transaction. The catalogue says *what a product is*; deliveries and dispenses say *what moved*; the inventory item is the running balance that ties them together. There is exactly one inventory item per product-per-location pair, so "Paracetamol in the ward pharmacy" is always a single, authoritative number.
+### How the count changes
 
-## How quantity is maintained
+Every inventory item belongs to one product and one location. Care changes the count in these situations:
 
-You do not type stock counts into Care by hand. The system creates and updates inventory items for you as supply events happen, so the count always reflects what actually moved rather than what someone remembered to enter.
+- Someone receives a purchase delivery at the location and marks it complete.
+- Someone completes a supply delivery that moves stock to or from the location.
+- Someone dispenses a medicine to a patient from this stock.
 
-- **Deliveries in** raise the count — completed [supply deliveries](../supply/supply-delivery.mdx) arriving at the location add to the balance
-- **Deliveries out** lower the count — stock sent onward to another location is subtracted
-- **Dispenses** lower the count — each [medication dispense](../medications/medication-dispense.mdx) drawn from the line removes units
+### Status
 
-Because the count is recomputed from these source records, it can read negative if more was dispensed or shipped out than the system recorded coming in — a useful signal that a delivery was missed or a count is off, rather than a number to overwrite.
-
-## Lifecycle
-
-```text
-active → inactive
-active → entered_in_error
-```
-
-- **active** — the stock line is live and dispensable; this is the state every newly tracked product starts in
-- **inactive** — no longer actively dispensed, for example when stock is damaged or a product is being phased out at that location
-- **entered_in_error** — the line was created by mistake and should be disregarded
-
-Changing the status is the one thing people do to an inventory item directly; the quantity itself is always system-maintained.
-
-## How it connects
-
-An inventory item sits at the centre of the supply picture, linking the catalogue to real-world movement:
-
-- It points to a [product](../supply/product.mdx), which in turn describes the substance or device through [product knowledge](../definitions/product-knowledge.mdx)
-- It belongs to a [location](../facility/location.mdx) inside a facility — the physical place the stock lives
-- Its balance is driven by [supply deliveries](../supply/supply-delivery.mdx) (replenishment and transfers) and [medication dispenses](../medications/medication-dispense.mdx) (consumption at the bedside)
-
-Because a location or product cannot be deleted while stock rows still reference it, the inventory layer protects the integrity of your supply history.
+| Status | Description |
+| --- | --- |
+| Active | The stock count is current and in use. |
+| Inactive | The stock count is no longer in use. |
+| Entered in Error | Someone recorded the stock count by mistake. |
 
 ## Permissions
 
-Access to inventory items is governed at the facility level by role-based permissions.
+Permissions apply within a facility.
 
-| Permission | Description | System Roles |
+| Permission | Roles | What it allows |
 | --- | --- | --- |
-| `can_read_inventory_item` | View the stock lines and on-hand quantities at a facility location | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
-
-Roles are granted through a user's facility and organization memberships, and permissions cascade down the organization tree — so a user with facility access sees the inventory for the locations that fall under it.
+| Can Read Inventory Item | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | View the stock levels at a location. |
 
 ## Related
 
-- Reference: [Inventory Item (technical)](../../references/supply/inventory-item.mdx)
-- Concept: [Product](../supply/product.mdx)
-- Concept: [Supply Delivery](../supply/supply-delivery.mdx)
-- Concept: [Medication Dispense](../medications/medication-dispense.mdx)
-- Concept: [Location](../facility/location.mdx)
+- Flow: [View stock levels at a location](../../flows/supply/inventory-item/view-stock-levels.mdx)
+- Concept: [Product](../../concepts/supply/product.mdx) — the catalog and stocked-batch records that an inventory item counts
+- Concept: [Purchase Delivery](../../concepts/supply/purchase-delivery.mdx) — receiving one increases stock
+- Concept: [Supply Delivery](../../concepts/supply/supply-delivery.mdx) — completing one moves stock between locations

versioned_docs/version-3.1/concepts/supply/product.mdx

@@ -4,65 +4,89 @@ sidebar_position: 1
 
 # Product
 
-A **product** in Care is a specific batch of a stockable item — a medication, nutritional product, or consumable — as it physically exists at one facility. It is the bridge between your catalogue ("we carry Paracetamol 500mg") and your shelves ("this box, lot A1234, expiring next March").
+## Definition
 
-## What it represents
+Care keeps two kinds of records for every item that a facility stocks or dispenses. A **Product Knowledge** entry is the catalog definition of a type of product, for example "Paracetamol 500mg tablet". A **Product** is one facility's stocked batch of that catalog entry, with its own lot number, expiry date, and purchase price.
 
-In Care's FHIR-aligned model, a product maps loosely to the **Medication** / supply resource family, but Care treats it as the concrete, batch-level instance of a catalogue definition. It captures:
+Note: Care does not map these two records to a single named FHIR R5 resource.
 
-- **Batch detail** — the lot number and expiry date that make one delivery distinct from the next
-- **Pricing & packing** — the purchase price for this batch and the number of units in a standard pack
-- **Catalogue link** — which product definition this batch instantiates
-- **Billing link** — an optional charge definition so the item can be billed when it is used
-- **Status** — whether this batch is in use, retired, or was recorded in error
+## Key Attributes
 
-The key distinction: a product is neither the catalogue entry nor your stock count. The catalogue entry describes *what* an item is in the abstract; a product describes *this particular batch* at a facility; the running quantity on hand is tracked separately by inventory. One catalogue entry can have many products underneath it — one per batch received.
+### Product Knowledge
 
-## How it connects
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the catalog entry. This is required. |
+| Slug | A short unique code that identifies the catalog entry. This is required. |
+| Product Type | The kind of product: Medication, Nutritional Product, or Consumable. This is required. |
+| Category | The group that the catalog entry belongs to. This is required. |
+| Code | A standard medical code for the product. This is optional. |
+| Base Unit | The unit that measures the product, for example tablet or millilitre. This is required. |
+| Status | The stage of the catalog entry. This is required. |
+| Alternate Identifier | Another identifier for the product. This is optional. |
+| Alternate names | Trade names and other aliases of the product. This is optional. |
+| Storage guidelines | The instructions to store the product. This is optional. |
 
-A product sits in the middle of the supply chain, pointing up at the catalogue and down at the stock:
+### Product
 
-- **[Product knowledge](../definitions/product-knowledge.mdx)** — the catalogue definition the product instantiates. Name, codes, dosage form, and product type are read from here, never copied onto the product. A product cannot exist without one.
-- **[Inventory item](../supply/inventory-item.mdx)** — tracks the quantity of a product on hand at a location. The product says *what batch*; the inventory item says *how much, and where*.
-- **[Facility](../facility/facility.mdx)** — every product belongs to exactly one facility, scoped to where it was received rather than shared across your network.
-- **[Charge item definition](../definitions/charge-item-definition.mdx)** — an optional link that raises a charge automatically when the product is billed.
+| Components | What it captures |
+| --- | --- |
+| Status | The stage of the stocked batch. This is required. |
+| Product Knowledge | The catalog entry that the batch belongs to. This is required. You select it when you create the product, and you cannot change it later. |
+| Lot Number | The batch number that the supplier prints on the product. This is optional. |
+| Expiration Date | The date that the batch expires on. This is required. |
+| Standard Pack Size | The number of base units in one pack. This is optional. |
+| Purchase Price | The price that the facility paid for the product. This is optional. |
+| Charge Item Definition | The price that Care uses to bill this product to a patient. This is optional. |
 
-## Types
+## Status
 
-A product's type comes from its catalogue definition, not from the product itself, so you classify an item once and every batch you receive inherits that classification. Care recognises three kinds:
+Product Knowledge and Product use different status values.
 
-- **Medication** — a drug or therapeutic agent
-- **Nutritional product** — feeds, supplements, and similar items
-- **Consumable** — gloves, syringes, dressings, and other single-use supplies
+### Product Knowledge status
 
-## Lifecycle
+| Status | Description |
+| --- | --- |
+| Draft | The catalog entry is not ready for use. |
+| Active | Staff can use the catalog entry. |
+| Retired | The catalog entry is no longer in use. |
 
-```text
-active → inactive
-active → entered_in_error
-```
+### Product status
 
-- **active** — the batch is in use and can be dispensed, consumed, or billed
-- **inactive** — the batch is no longer in use but is retained for history (for example, stock that is fully consumed or expired)
-- **entered_in_error** — the record was created by mistake; it is kept for auditability rather than deleted
+| Status | Description |
+| --- | --- |
+| Active | The facility stocks and dispenses this batch. |
+| Inactive | The facility no longer uses this batch. |
+| Entered in Error | Someone created this batch by mistake. |
 
-Unlike some clinical resources, a product keeps no server-side status history — it simply reflects its current status.
+Note: Care has no delete action for these records. Retire a catalog entry, or set a product to Inactive or Entered in Error.
+
+## Ownership and Sharing
+
+A product always belongs to one catalog entry and one facility. A catalog entry is either global or private. A superuser manages global catalog entries, and all facilities share them. A facility admin manages the private catalog entries of that facility.
+
+## How Products Connect to Stock
+
+An inventory item tracks how much of a product is in stock at one location. Staff most often create a new product while they receive a purchase delivery. When a delivered item is not already in stock, the person who receives the delivery creates the product record for that batch, expiry date, and price.
+
+You can link a product to a charge item definition. Care then creates a billable charge item when staff dispense the product.
 
 ## Permissions
 
-Access to products is granted per facility, so who can see or change a batch depends on the roles a user holds there.
+Permissions apply within a facility.
 
-| Permission | Description | System Roles |
+| Permission | Roles | What it allows |
 | --- | --- | --- |
-| `can_write_product` | Create, update, or upsert products (batches) at a facility | Facility Admin, Admin |
-| `can_read_product` | List and view products at a facility | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist |
-
-Roles are assigned through facility and organization memberships, and permissions cascade down the organization tree — a role granted on a parent organization is inherited by the facilities beneath it. Creating or editing products is limited to administrators, while a broad set of clinical and pharmacy roles can read them.
+| Can Create Product Knowledge on Facility | Facility Admin, Admin | Create and edit catalog entries. |
+| Can Create Product on Facility | Facility Admin, Admin | Create and edit products. |
+| Can Read Product Knowledge | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | View catalog entries. |
+| Can Read Product | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | View products. |
 
 ## Related
 
-- Reference: [Product (technical)](../../references/supply/product.mdx)
-- Concept: [Product knowledge](../definitions/product-knowledge.mdx)
-- Concept: [Inventory item](../supply/inventory-item.mdx)
-- Concept: [Supply request](../supply/supply-request.mdx)
-- Concept: [Charge item definition](../definitions/charge-item-definition.mdx)
+- Flow: [Add a product to the catalog](../../flows/supply/product/add-product-to-catalog.mdx)
+- Flow: [Edit or retire a catalog entry](../../flows/supply/product/edit-retire-catalog-entry.mdx)
+- Flow: [Add a product instance](../../flows/supply/product/add-product-instance.mdx)
+- Flow: [Edit a product instance](../../flows/supply/product/edit-product-instance.mdx)
+- Concept: [Inventory Item](../../concepts/supply/inventory-item.mdx)
+- Concept: [Purchase Delivery](../../concepts/supply/purchase-delivery.mdx)

versioned_docs/version-3.1/concepts/supply/purchase-delivery.mdx

@@ -0,0 +1,75 @@
+---
+sidebar_position: 5
+---
+
+# Purchase Delivery
+
+## Definition
+
+A **purchase delivery** in Care records stock that arrives at your facility from an outside vendor. It bundles one or more [delivered items](https://build.fhir.org/supplydelivery.html) under a single delivery. When you complete the delivery, Care updates the stock levels at the destination location.
+
+Care uses one delivery mechanism for two purposes. A purchase delivery names an external vendor and brings stock into the facility. A supply delivery names an internal source location and moves stock between two locations in the same facility. Both types use the same fields, the same statuses, and the same screens. The vendor or the source location tells you which type you work with.
+
+## Key Attributes
+
+| Components | What it captures |
+| --- | --- |
+| Name | The name of the delivery. This field is required. |
+| Note | Extra information about the delivery. This field is optional. |
+| Vendor/Distributor | The external supplier organization that sends the goods. This field is required. |
+| Destination | The facility location that receives the goods. This field is required, and it defaults to your current location. |
+| Purchase Order | The purchase order that this delivery fulfills. This link is optional. |
+
+### Purchase Order link
+
+You can link a purchase delivery to the purchase order that it fulfills. Care then fills in the name, the vendor, the destination, and the tags from that purchase order.
+
+### Delivered items
+
+You add delivered items after you create the delivery. Each delivered item records these details:
+
+- The product that arrives
+- The quantity
+- The pack quantity and the pack size
+- The purchase price
+- The tax amount and the discount amount
+- The condition, either Normal or Damaged
+
+If the item is not a known product instance, you can create the product instance while you add the item to the delivery. For more information, see the [Product](../../concepts/supply/product.mdx) concept.
+
+### Status
+
+| Status | Description |
+| --- | --- |
+| Draft | You started the delivery, but it is not ready for receipt. |
+| Pending | The delivery waits for receipt at the destination location. |
+| Completed | The facility received the delivery. Care updates the stock at the destination location. |
+| Abandoned | The delivery stopped before receipt. |
+| Entered in Error | Someone recorded the delivery by mistake. |
+
+## Relationships
+
+- When you complete a purchase delivery, Care creates or updates the inventory item stock count at the destination location.
+- A purchase delivery can reference the purchase order that it fulfills.
+- If a delivery is linked to a patient, the delivery records a medication return. When you complete it, Care creates a refund invoice and reversed charge items on that patient's billing account. If you mark the delivery as Entered in Error, Care reverses the refund invoice and the reversed charge items.
+
+## Permissions
+
+Care controls purchase deliveries with facility-scoped permissions.
+
+| Permission | Roles | What it allows |
+| --- | --- | --- |
+| Can Create External Supply Delivery on Facility | Facility Admin, Admin | Create or edit a purchase delivery and its delivered items. |
+| Can Read Supply Delivery | Facility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist | View a purchase delivery. |
+
+## Related
+
+- Flow: [Create a purchase delivery](../../flows/supply/purchase-delivery/create-purchase-delivery.mdx)
+- Flow: [Add delivered items to a purchase delivery](../../flows/supply/purchase-delivery/add-items-purchase-delivery.mdx)
+- Flow: [Receive and complete a purchase delivery](../../flows/supply/purchase-delivery/receive-purchase-delivery.mdx)
+- Flow: [View a purchase delivery](../../flows/supply/purchase-delivery/view-purchase-delivery.mdx)
+- Concept: [Supply Delivery](../../concepts/supply/supply-delivery.mdx)
+- Concept: [Purchase Order](../../concepts/supply/purchase-order.mdx)
+- Concept: [Product](../../concepts/supply/product.mdx)
+- Concept: [Inventory Item](../../concepts/supply/inventory-item.mdx)
+- Concept: [Invoice](../../concepts/billing/invoice.mdx)