Inventory

Supply Delivery

A supply delivery records product moving into a destination location — either from another location or from an external supplier. Deliveries and dispensing together drive facility stock: supply delivered − supply dispensed = current stock. Each…

3.1 · versioned documentation · 7 min read

A supply delivery records product moving into a destination location — either from another location or from an external supplier. Deliveries and dispensing together drive facility stock: supply delivered − supply dispensed = current stock. Each delivery belongs to a DeliveryOrder, the shipment grouping usually created from a supply request.

Source:

• Model: care/emr/models/supply_delivery.py
• Resource specs: spec.py · delivery_order.py

The Django model is a thin store: status, delivery_type, and supplied_item_condition are plain CharFields, and extensions is an opaque JSONField. Enum values, validation, and the read/write schema split live in the Pydantic resource specs below.

Models

Both extend EMRBaseModel, which supplies external_id, the created_by/updated_by and created_date/modified_date audit fields, soft-delete via deleted, and history/meta JSON.

SupplyDelivery fields

Delivered item & quantity

Status & classification

Links & pricing

SupplyDelivery enum values

These are str enums in spec.py — the stored value equals the member value (snake_case), not a FHIR URI.

SupplyDeliveryStatusOptions (status)

SupplyDeliveryConditionOptions (supplied_item_condition)

SupplyDeliveryTypeOptions (delivery_type)

Related models

DeliveryOrder

A DeliveryOrder is one logical shipment. It groups its SupplyDelivery rows and moves stock between two facility locations, or from an external supplier into a facility.

supplier        → FK Organization (CASCADE, nullable)      -- external/source supplier
origin          → FK FacilityLocation (CASCADE, nullable)  -- related_name="origin_delivery_orders"
destination     → FK FacilityLocation (CASCADE)            -- related_name="destination_delivery_orders"
patient         → FK Patient (PROTECT, nullable)           -- patient the order is dispensed to
patient_invoice → FK Invoice (PROTECT, nullable)           -- linked billing invoice

patient and patient_invoice use PROTECT: a referenced patient or invoice can't be deleted while a delivery order points to it.

SupplyDeliveryOrderStatusOptions (status)

Resource specs (API schema)

Every spec extends EMRResource (base.py): serialize builds the read payload from the DB object (perform_extra_serialization hook), de_serialize builds the DB object from the request (perform_extra_deserialization hook), and to_json() dumps the model excluding meta.

SupplyDelivery specs

Write validation (SupplyDeliveryWriteSpec):

• validate_quantity: when both supplied_item_pack_quantity and supplied_item_pack_size are set, supplied_item_quantity is overwritten with their product.
• validate_supplied_item (resolves order from external_id):
  • if order.origin is set → supplied_inventory_item is required (intra-facility stock move);
  • if order.origin is not set → supplied_item is required (external delivery);
  • supplied_item and supplied_inventory_item cannot both be provided.
• perform_extra_deserialization: resolves order by external_id; resolves supplied_item scoped to order.destination.facility; if order.origin exists, resolves supplied_inventory_item scoped to order.origin.facility; resolves supply_request by external_id.

Update (SupplyDeliveryUpdateSpec): perform_extra_deserialization re-resolves order from external_id only when order is provided.

Read serialization: perform_extra_serialization sets id = external_id and inlines related objects via their read specs — supplied_item → ProductReadSpec, supplied_inventory_item → InventoryItemReadSpec, supply_request → SupplyRequestReadSpec, order → SupplyDeliveryOrderReadSpec.

DeliveryOrder specs

Write validation (SupplyDeliveryOrderWriteSpec.perform_extra_deserialization):

• resolves destination (required), origin?, patient? by external_id;
• resolves supplier? constrained to org_type = product_supplier;
• patient and origin cannot be provided together;
• on create the status must be draft or pending.

Read serialization: id = external_id; inlines origin/destination via FacilityLocationListSpec, supplier via OrganizationReadSpec, patient via PatientListSpec; renders tags via SingleFacilityTagManager; exposes the linked invoice as patient_invoice_id (string); attaches audit users.

Extensions

extensions is not free-form JSON. On write, ExtensionValidator runs each registered handler for the resource type (supply_delivery / supply_delivery_order): unknown keys are dropped, and known keys are validated and re-serialized. On read, ExtensionListRenderer / ExtensionRetrieveRenderer render every registered extension for the resource (list vs retrieve variants).

API integration notes

• Coded fields carry the snake_case enum values above (e.g. status = "in_progress"), not FHIR URIs. Validate against the enum, not free text.
• A delivery is created against a DeliveryOrder (order is required on create). The order's origin decides whether you send supplied_inventory_item (intra-facility) or supplied_item (external) — never both.
• Send supplied_item_pack_quantity + supplied_item_pack_size to have supplied_item_quantity computed server-side; otherwise send supplied_item_quantity directly (whole units).
• A DeliveryOrder must start in draft or pending; completed/abandoned/entered_in_error are terminal.
• patient and origin are mutually exclusive on an order (patient dispense vs location-to-location move).
• extensions holds deployment-specific data, but only registered extension keys are persisted.

Related

• Reference: Supply Request
• Reference: Inventory Item
• Reference: Product
• Reference: Location
• Reference: Organization
• Reference: Patient
• Reference: Invoice
• Source: supply_delivery.py (model)
• Source: spec.py (SupplyDelivery specs)
• Source: delivery_order.py (DeliveryOrder specs)
• Source: base.py (EMRResource)

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/supply/supply-delivery.mdx:1 · f6e9f05f