View source for References/Supply Delivery

{{Doc header
|type=reference
|domain=supply
|title=Supply Delivery
|order=5
|introduced=3.0
|model=SupplyDelivery
|reference=References/Invoice
}}

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: <code>supply delivered − supply dispensed = current stock</code>. Each delivery belongs to a <code>DeliveryOrder</code>, the shipment grouping usually created from a [[References/Supply Request|supply request]].

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/supply_delivery.py <code>care/emr/models/supply_delivery.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/supply_delivery/spec.py <code>spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/inventory/supply_delivery/delivery_order.py <code>delivery_order.py</code>]

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

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>SupplyDelivery</code>
| A single line of delivered product (quantity, condition, source product/inventory)
|-
| <code>DeliveryOrder</code>
| Groups deliveries for a shipment between an origin and destination
|}

Both extend [[References/Base models &amp; conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, the <code>created_by</code>/<code>updated_by</code> and <code>created_date</code>/<code>modified_date</code> audit fields, soft-delete via <code>deleted</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>SupplyDelivery</code> fields ==

=== Delivered item &amp; quantity ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_item|type=FK → Product (CASCADE)|notes=Nullable. The product delivered. Required at the API layer only when the order has no <code>origin</code> (external delivery); scoped to <code>order.destination.facility</code> on write}}
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_inventory_item|type=FK → InventoryItem (CASCADE)|notes=Nullable. Specific inventory item (batch/lot) drawn from. Required at the API layer when the order has an <code>origin</code> (intra-facility move); scoped to <code>order.origin.facility</code>}}
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_item_quantity|type=DecimalField(max_digits=20, decimal_places=6)|notes=Nullable in DB. On write a <code>Decimal</code> with <code>decimal_places=0</code> (whole units); on read serialized as <code>int</code>. Auto-derived as <code>pack_quantity × pack_size</code> when both are given}}
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_item_pack_quantity|type=IntegerField|notes=Nullable; default <code>None</code>. Number of packs delivered}}
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_item_pack_size|type=IntegerField|notes=Nullable; default <code>None</code>. Units per pack}}
{{Field|model=SupplyDelivery|section=Delivered item &amp; quantity|name=supplied_item_condition|type=CharField(255)|notes=Optional. Condition of the delivered item — enum <code>SupplyDeliveryConditionOptions</code> (see below)}}
|}

=== Status &amp; classification ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyDelivery|section=Status &amp; classification|name=status|type=CharField(255)|notes=Required. Lifecycle state — enum <code>SupplyDeliveryStatusOptions</code> (see below)}}
{{Field|model=SupplyDelivery|section=Status &amp; classification|name=delivery_type|type=CharField(255)|notes=Enum <code>SupplyDeliveryTypeOptions</code> (<code>product</code> / <code>device</code>). Stored on the model but not exposed on the current Create/Update specs, so it can't be set through the API}}
|}

=== Links &amp; pricing ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyDelivery|section=Links &amp; pricing|name=supply_request|type=FK → SupplyRequest (CASCADE)|notes=Nullable. Request this delivery fulfils. Set by <code>external_id</code> on write}}
{{Field|model=SupplyDelivery|section=Links &amp; pricing|name=order|type=FK → DeliveryOrder (CASCADE)|notes=Nullable in DB, but '''required on create''' (referenced by <code>external_id</code>). Optional on update}}
{{Field|model=SupplyDelivery|section=Links &amp; pricing|name=total_purchase_price|type=DecimalField(max_digits=20, decimal_places=6)|notes=Nullable. Total purchase cost. Spec: <code>Decimal</code> <code>max_digits=20, decimal_places=6</code>}}
{{Field|model=SupplyDelivery|section=Links &amp; pricing|name=extensions|type=JSONField|notes=Default <code>{}</code>. Validated per registered extension handler for <code>ExtensionResource.supply_delivery</code> (see [[#resource-specs-api-schema}}
|}

=== <code>SupplyDelivery</code> enum values ===

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

==== <code>SupplyDeliveryStatusOptions</code> (<code>status</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>in_progress</code>
|-
| <code>completed</code>
|-
| <code>abandoned</code>
|-
| <code>entered_in_error</code>
|}

==== <code>SupplyDeliveryConditionOptions</code> (<code>supplied_item_condition</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>normal</code>
|-
| <code>damaged</code>
|}

==== <code>SupplyDeliveryTypeOptions</code> (<code>delivery_type</code>) ====

{| class="wikitable"
|-
! Value
|-
| <code>product</code>
|-
| <code>device</code>
|}

== Related models ==

=== <code>DeliveryOrder</code> ===

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

<syntaxhighlight lang="text">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</syntaxhighlight>
{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=name|type=CharField(255)|notes=Required. Human-readable order name}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=status|type=CharField(255)|notes=Required. Order lifecycle — enum <code>SupplyDeliveryOrderStatusOptions</code> (see below)}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=note|type=TextField|notes=Nullable. Free-text note}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=tags|type=ArrayField[int]|notes=Default <code>[]</code>. Tag IDs; rendered via <code>SingleFacilityTagManager</code> on read}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=supplier|type=FK → Organization (CASCADE)|notes=Nullable. On write must be an Organization with <code>org_type = product_supplier</code>}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=origin|type=FK → FacilityLocation (CASCADE)|notes=Nullable. Source location; absence means stock is entering from an external <code>supplier</code>}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=destination|type=FK → FacilityLocation (CASCADE)|notes='''Required.''' Receiving location}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=patient|type=FK → Patient (PROTECT)|notes=Nullable. Patient the order is dispensed to. Cannot be set together with <code>origin</code>}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=patient_invoice|type=FK → Invoice (PROTECT)|notes=Nullable. Linked billing invoice; serialized as <code>patient_invoice_id</code> on read}}
{{Field|model=SupplyDelivery|section=DeliveryOrder|name=extensions|type=JSONField|notes=Default <code>{}</code>. Validated for <code>ExtensionResource.supply_delivery_order</code>}}
|}

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

==== <code>SupplyDeliveryOrderStatusOptions</code> (<code>status</code>) ====

{| class="wikitable"
|-
! Value
! Notes
|-
| <code>draft</code>
| Allowed on create
|-
| <code>pending</code>
| Allowed on create
|-
| <code>in_progress</code>
|
|-
| <code>completed</code>
| Terminal (in <code>SUPPLY_DELIVERY_ORDER_COMPLETED_STATUSES</code>)
|-
| <code>abandoned</code>
| Terminal (in <code>SUPPLY_DELIVERY_ORDER_COMPLETED_STATUSES</code>)
|-
| <code>entered_in_error</code>
| Terminal (in <code>SUPPLY_DELIVERY_ORDER_COMPLETED_STATUSES</code>)
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>]): <code>serialize</code> builds the read payload from the DB object (<code>perform_extra_serialization</code> hook), <code>de_serialize</code> builds the DB object from the request (<code>perform_extra_deserialization</code> hook), and <code>to_json()</code> dumps the model excluding <code>meta</code>.

=== <code>SupplyDelivery</code> specs ===

{| class="wikitable"
|-
! Spec
! Role
! Exposes / behaviour
|-
| <code>BaseSupplyDeliverySpec</code>
| shared
| <code>id</code>, <code>status</code> (required), <code>supplied_item_condition?</code>, <code>total_purchase_price?</code>. <code>__exclude__ = [&quot;supplied_item&quot;, &quot;supply_request&quot;, &quot;supplied_inventory_item&quot;]</code> (these are resolved by hooks, not direct field copy)
|-
| <code>SupplyDeliveryWriteSpec</code>
| write · create
| Adds <code>supplied_item_pack_quantity?</code>, <code>supplied_item_pack_size?</code>, <code>supplied_item_quantity</code> (Decimal, <code>decimal_places=0</code>), <code>supplied_item?</code>, <code>supplied_inventory_item?</code>, <code>supply_request?</code>, <code>order</code> ('''required'''), <code>extensions</code>. Mixes in <code>ExtensionValidator</code>
|-
| <code>SupplyDeliveryUpdateSpec</code>
| write · update
| <code>order?</code> only (plus shared base fields + <code>extensions</code>). Mixes in <code>ExtensionValidator</code>
|-
| <code>SupplyDeliveryReadSpec</code>
| read · list
| <code>supplied_item_quantity: int</code>, <code>created_date</code>, <code>modified_date</code>, <code>supplied_item_pack_quantity?</code>, <code>supplied_item_pack_size?</code>, <code>extensions</code>, and nested objects <code>supplied_item</code>, <code>supplied_inventory_item</code>, <code>supply_request</code>, <code>order</code> (serialized as <code>dict</code>). Mixes in <code>ExtensionListRenderer</code>
|-
| <code>SupplyDeliveryRetrieveSpec</code>
| read · detail
| Extends <code>SupplyDeliveryReadSpec</code>; adds <code>created_by</code>/<code>updated_by</code> (<code>UserSpec</code>). Mixes in <code>ExtensionRetrieveRenderer</code>
|}

'''Write validation (<code>SupplyDeliveryWriteSpec</code>):'''

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

'''Update (<code>SupplyDeliveryUpdateSpec</code>):''' <code>perform_extra_deserialization</code> re-resolves <code>order</code> from <code>external_id</code> only when <code>order</code> is provided.

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

=== <code>DeliveryOrder</code> specs ===

{| class="wikitable"
|-
! Spec
! Role
! Exposes / behaviour
|-
| <code>BaseSupplyDeliveryOrderSpec</code>
| shared
| <code>id</code>, <code>status</code> (required), <code>name</code> (required), <code>note?</code>. Mixes in <code>ExtensionValidator</code>
|-
| <code>SupplyDeliveryOrderWriteSpec</code>
| write · create/update
| Adds <code>supplier?</code>, <code>origin?</code>, <code>destination</code> ('''required'''), <code>patient?</code> (all by <code>external_id</code>)
|-
| <code>SupplyDeliveryOrderReadSpec</code>
| read · list
| Nested <code>origin?</code>, <code>destination</code>, <code>supplier?</code>, <code>patient?</code> (<code>dict</code>), <code>tags</code>, <code>patient_invoice_id?</code>, <code>created_date</code>, <code>modified_date</code>, <code>created_by?</code>, <code>updated_by?</code>. Mixes in <code>ExtensionListRenderer</code>
|-
| <code>SupplyDeliveryOrderRetrieveSpec</code>
| read · detail
| Extends <code>SupplyDeliveryOrderReadSpec</code> (no extra fields). Mixes in <code>ExtensionRetrieveRenderer</code>
|}

'''Write validation (<code>SupplyDeliveryOrderWriteSpec.perform_extra_deserialization</code>):'''

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

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

=== Extensions ===

<code>extensions</code> is not free-form JSON. On write, <code>ExtensionValidator</code> runs each registered handler for the resource type (<code>supply_delivery</code> / <code>supply_delivery_order</code>): unknown keys are dropped, and known keys are validated and re-serialized. On read, <code>ExtensionListRenderer</code> / <code>ExtensionRetrieveRenderer</code> 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. <code>status = &quot;in_progress&quot;</code>), not FHIR URIs. Validate against the enum, not free text.
* A delivery is created against a <code>DeliveryOrder</code> (<code>order</code> is required on create). The order's <code>origin</code> decides whether you send <code>supplied_inventory_item</code> (intra-facility) or <code>supplied_item</code> (external) — never both.
* Send <code>supplied_item_pack_quantity</code> + <code>supplied_item_pack_size</code> to have <code>supplied_item_quantity</code> computed server-side; otherwise send <code>supplied_item_quantity</code> directly (whole units).
* A <code>DeliveryOrder</code> must start in <code>draft</code> or <code>pending</code>; <code>completed</code>/<code>abandoned</code>/<code>entered_in_error</code> are terminal.
* <code>patient</code> and <code>origin</code> are mutually exclusive on an order (patient dispense vs location-to-location move).
* <code>extensions</code> holds deployment-specific data, but only registered extension keys are persisted.

{{Related}}