Skip to main content
PATCH
{micro_service_base_url}
/
orders
/
{order_id}
/
order-items
/
{order_item_id}
{
  "success": true,
  "message": "<string>",
  "order_item_id": "<string>",
  "updated_fields": [
    {}
  ],
  "timestamp": "<string>"
}
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.
This endpoint is designed for updating item metadata and preparation instructions. For quantity changes or item removal, use the Patch Order Cart endpoint instead.

​
Path Parameters

​
order_id
string
required
The unique identifier of the order containing the item to update
​
order_item_id
string
required
The unique identifier of the specific order item to update

​
Request Body

​
special_instructions
string
Updated special preparation instructions for this item
​
store_item_name
string
Updated product name as displayed in store
​
store_item_description
string
Updated product description
​
store_item_category
string
Updated product category classification
​
store_item_size
string
Updated item size specification
​
preparation_notes
string
Internal notes for kitchen staff or fulfillment team
​
updated_by
string
Employee ID who made the update (for audit trail)

​
Response

​
success
boolean
Indicates whether the update was successful
​
message
string
Confirmation message or error details
​
order_item_id
string
The ID of the updated order item
​
updated_fields
array
List of fields that were successfully updated
​
timestamp
string
Timestamp when the update was applied

​
Request Example

{
  "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

{
  "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"
}
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
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.
Best Practice: Always include the updated_by field to maintain a clear audit trail of who made changes to the order.

​
Use Cases

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

​
Error Responses

Order Item Not Found
{
  "success": false,
  "message": "Order item not found",
  "error_code": "ITEM_NOT_FOUND",
  "order_item_id": "invalid-item-id"
}
Order Not Modifiable
{
  "success": false,
  "message": "Order cannot be modified in current status",
  "error_code": "ORDER_NOT_MODIFIABLE",
  "current_status": "completed"
}
Invalid Field Value
{
  "success": false,
  "message": "Invalid value provided for field",
  "error_code": "INVALID_FIELD_VALUE",
  "field": "store_item_category",
  "provided_value": "InvalidCategory"
}
Validation Error
{
  "success": false,
  "message": "Field validation failed",
  "error_code": "VALIDATION_ERROR",
  "validation_errors": [
    {
      "field": "special_instructions",
      "error": "Must be less than 500 characters"
    }
  ]
}
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.
Character Limits: Special instructions and descriptions have character limits. Ensure your updates stay within these bounds to avoid validation errors.

​
Field Validation Rules

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.
⌘I