> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lulacommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Order Items

> Update specific details of an order item including special instructions, product information, and item specifications.

This endpoint allows you to update specific details of an order item after the order has been created. You can modify special instructions, update product descriptions, change categories, or adjust item specifications without affecting quantity or pricing.

<Info>
  This endpoint is designed for updating item metadata and preparation instructions. For quantity changes or item removal, use the Patch Order Cart endpoint instead.
</Info>

### Path Parameters

<ParamField path="order_id" type="string" required>
  The unique identifier of the order containing the item to update
</ParamField>

<ParamField path="order_item_id" type="string" required>
  The unique identifier of the specific order item to update
</ParamField>

### Request Body

<ParamField body="special_instructions" type="string" optional>
  Updated special preparation instructions for this item
</ParamField>

<ParamField body="store_item_name" type="string" optional>
  Updated product name as displayed in store
</ParamField>

<ParamField body="store_item_description" type="string" optional>
  Updated product description
</ParamField>

<ParamField body="store_item_category" type="string" optional>
  Updated product category classification
</ParamField>

<ParamField body="store_item_size" type="string" optional>
  Updated item size specification
</ParamField>

<ParamField body="preparation_notes" type="string" optional>
  Internal notes for kitchen staff or fulfillment team
</ParamField>

<ParamField body="updated_by" type="string" optional>
  Employee ID who made the update (for audit trail)
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the update was successful
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message or error details
</ResponseField>

<ResponseField name="order_item_id" type="string">
  The ID of the updated order item
</ResponseField>

<ResponseField name="updated_fields" type="array">
  List of fields that were successfully updated
</ResponseField>

<ResponseField name="timestamp" type="string">
  Timestamp when the update was applied
</ResponseField>

### Request Example

```json theme={null}
{
  "special_instructions": "Pack item carefully - fragile",
  "store_item_name": "Pearson Nut Roll King",
  "store_item_description": "Crunchy, salty peanut roll with caramel center",
  "store_item_category": "Snacks",
  "store_item_size": "1 count",
  "preparation_notes": "Check expiration date before packing",
  "updated_by": "emp_12345"
}
```

### Response Example

```json theme={null}
{
  "success": true,
  "message": "Order item successfully updated",
  "order_item_id": "7fbe2819-5bc6-4340-8dfe-a5605272a32b",
  "updated_fields": [
    "special_instructions",
    "store_item_name",
    "store_item_description",
    "store_item_category",
    "store_item_size",
    "preparation_notes"
  ],
  "timestamp": "2024-01-15T14:30:00Z"
}
```

<Accordion title="Update Tracking">
  When an order item is updated, the following occurs:

  1. **Field Validation**: All provided fields are validated for format and content
  2. **Audit Log**: Change is recorded with timestamp and user information
  3. **Fulfillment Update**: Kitchen/fulfillment systems are notified of changes
  4. **History Tracking**: Previous values are preserved for audit trail
  5. **Status Check**: Order status is verified to ensure modifications are allowed
</Accordion>

<Note>
  **Immutable Fields**: Certain fields like quantity, pricing, and core product identifiers cannot be updated through this endpoint. Use the appropriate order modification endpoints for those changes.
</Note>

<Tip>
  **Best Practice**: Always include the updated\_by field to maintain a clear audit trail of who made changes to the order.
</Tip>

### Use Cases

<Accordion title="Common Update Scenarios">
  **Special Instructions Updates**

  * Add dietary restrictions or allergies
  * Update preparation preferences
  * Include delivery instructions

  **Product Information Corrections**

  * Fix product name typos
  * Update descriptions for clarity
  * Correct category classifications

  **Fulfillment Notes**

  * Add handling instructions
  * Include quality control notes
  * Specify packing requirements

  **Customer Service Adjustments**

  * Update based on customer requests
  * Clarify ambiguous instructions
  * Add additional context for staff
</Accordion>

### Error Responses

<Accordion title="Common Error Scenarios">
  **Order Item Not Found**

  ```json theme={null}
  {
    "success": false,
    "message": "Order item not found",
    "error_code": "ITEM_NOT_FOUND",
    "order_item_id": "invalid-item-id"
  }
  ```

  **Order Not Modifiable**

  ```json theme={null}
  {
    "success": false,
    "message": "Order cannot be modified in current status",
    "error_code": "ORDER_NOT_MODIFIABLE",
    "current_status": "completed"
  }
  ```

  **Invalid Field Value**

  ```json theme={null}
  {
    "success": false,
    "message": "Invalid value provided for field",
    "error_code": "INVALID_FIELD_VALUE",
    "field": "store_item_category",
    "provided_value": "InvalidCategory"
  }
  ```

  **Validation Error**

  ```json theme={null}
  {
    "success": false,
    "message": "Field validation failed",
    "error_code": "VALIDATION_ERROR",
    "validation_errors": [
      {
        "field": "special_instructions",
        "error": "Must be less than 500 characters"
      }
    ]
  }
  ```
</Accordion>

<Warning>
  **Status Restrictions**: Order items can only be updated when the order is in modifiable status (pending, accepted, in\_progress). Completed or canceled orders cannot be modified.
</Warning>

<Note>
  **Character Limits**: Special instructions and descriptions have character limits. Ensure your updates stay within these bounds to avoid validation errors.
</Note>

### Field Validation Rules

<Accordion title="Validation Requirements">
  **special\_instructions**

  * Maximum length: 500 characters
  * Can include basic punctuation and numbers
  * No HTML or special formatting allowed

  **store\_item\_name**

  * Maximum length: 200 characters
  * Must be unique within the order
  * Cannot be empty if provided

  **store\_item\_description**

  * Maximum length: 1000 characters
  * Supports basic formatting
  * Optional field

  **store\_item\_category**

  * Must match existing category in system
  * Case-sensitive matching
  * Cannot be null if provided

  **store\_item\_size**

  * Maximum length: 50 characters
  * Free-form text field
  * Commonly used values: "Small", "Medium", "Large", "1 count", etc.
</Accordion>