Update Order Items

Update Order Items

curl --request PATCH \
  --url 'https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "special_instructions": "<string>",
  "store_item_name": "<string>",
  "store_item_description": "<string>",
  "store_item_category": "<string>",
  "store_item_size": "<string>",
  "preparation_notes": "<string>",
  "updated_by": "<string>"
}
'

import requests

url = "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}"

payload = {
    "special_instructions": "<string>",
    "store_item_name": "<string>",
    "store_item_description": "<string>",
    "store_item_category": "<string>",
    "store_item_size": "<string>",
    "preparation_notes": "<string>",
    "updated_by": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    special_instructions: '<string>',
    store_item_name: '<string>',
    store_item_description: '<string>',
    store_item_category: '<string>',
    store_item_size: '<string>',
    preparation_notes: '<string>',
    updated_by: '<string>'
  })
};

fetch('https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'special_instructions' => '<string>',
    'store_item_name' => '<string>',
    'store_item_description' => '<string>',
    'store_item_category' => '<string>',
    'store_item_size' => '<string>',
    'preparation_notes' => '<string>',
    'updated_by' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}"

	payload := strings.NewReader("{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}")
  .header("Content-Type", "application/json")
  .body("{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "order_item_id": "<string>",
  "updated_fields": [
    {}
  ],
  "timestamp": "<string>"
}

PATCH

{micro_service_base_url}

orders

{order_id}

order-items

{order_item_id}

Update Order Items

curl --request PATCH \
  --url 'https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "special_instructions": "<string>",
  "store_item_name": "<string>",
  "store_item_description": "<string>",
  "store_item_category": "<string>",
  "store_item_size": "<string>",
  "preparation_notes": "<string>",
  "updated_by": "<string>"
}
'

import requests

url = "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}"

payload = {
    "special_instructions": "<string>",
    "store_item_name": "<string>",
    "store_item_description": "<string>",
    "store_item_category": "<string>",
    "store_item_size": "<string>",
    "preparation_notes": "<string>",
    "updated_by": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    special_instructions: '<string>',
    store_item_name: '<string>',
    store_item_description: '<string>',
    store_item_category: '<string>',
    store_item_size: '<string>',
    preparation_notes: '<string>',
    updated_by: '<string>'
  })
};

fetch('https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'special_instructions' => '<string>',
    'store_item_name' => '<string>',
    'store_item_description' => '<string>',
    'store_item_category' => '<string>',
    'store_item_size' => '<string>',
    'preparation_notes' => '<string>',
    'updated_by' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}"

	payload := strings.NewReader("{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}")
  .header("Content-Type", "application/json")
  .body("{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/{{micro_service_base_url}}/orders/{{order_id}}/order-items/{{order_item_id}}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"special_instructions\": \"<string>\",\n  \"store_item_name\": \"<string>\",\n  \"store_item_description\": \"<string>\",\n  \"store_item_category\": \"<string>\",\n  \"store_item_size\": \"<string>\",\n  \"preparation_notes\": \"<string>\",\n  \"updated_by\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

The unique identifier of the order containing the item to update

string

required

The unique identifier of the specific order item to update

Request Body

string

Updated special preparation instructions for this item

string

Updated product name as displayed in store

string

Updated product description

string

Updated product category classification

string

Updated item size specification

string

Internal notes for kitchen staff or fulfillment team

string

Employee ID who made the update (for audit trail)

Response

boolean

Indicates whether the update was successful

string

Confirmation message or error details

string

The ID of the updated order item

array

List of fields that were successfully updated

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

Update Tracking

When an order item is updated, the following occurs:

Field Validation: All provided fields are validated for format and content
Audit Log: Change is recorded with timestamp and user information
Fulfillment Update: Kitchen/fulfillment systems are notified of changes
History Tracking: Previous values are preserved for audit trail
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

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

Error Responses

Common Error Scenarios

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

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.

API Documentation - Legacy

API Documentation - Latest

Path Parameters

Request Body

Response

Request Example

Response Example

Use Cases

Error Responses

Field Validation Rules

​Path Parameters

​Request Body

​Response

​Request Example

​Response Example

​Use Cases

​Error Responses

​Field Validation Rules

Path Parameters

Request Body

Response

Request Example

Response Example

Use Cases

Error Responses

Field Validation Rules