# UpdatePurchaseItem

## Permission Scope

purchaseItem

## Overview

UpdatePurchaseItem changes the purchasing defaults of an already adopted item.

## Business Rules

- The referenced item must already hold a purchasing record
- Only fields present in the input are changed; absent fields keep their stored values
- Changing `requiresPhysicalReceipt` affects only lines entered afterwards — existing purchase order lines keep the value they froze at entry
- Host-defined custom fields are persisted alongside the builtin columns; a builtin column always wins over a custom field of the same name

## Process Flow

```mermaid
flowchart TD
    A[Receive update request for an item] --> B{Item has a purchasing record?}
    B -->|No| C[Return ITEM_NOT_PURCHASABLE]
    B -->|Yes| D[Apply the present fields to the record]
    D --> E[Return updated purchasing record]
```

## External Dependencies

- None

## Error Scenarios

- **ITEM_NOT_PURCHASABLE**: Referenced item holds no purchasing record and cannot be purchased

## Test Cases

- updates the receipt expectation of an adopted item
- leaves stored values unchanged for fields absent from the input
- returns error when the item has no purchasing record
- persists host-defined custom fields alongside the builtin columns