UpdateOrderStatusRequest

UpdateOrderStatusRequest is a data transfer object used by order management systems to request a transition of an order’s status. It is commonly submitted by fulfillment, customer service, or integration services to drive lifecycle changes and downstream workflows. The request helps enforce valid state transitions and enables event-driven processing.

Typical fields

- orderId: string; required; the unique identifier of the order.

- newStatus: string or enum; required; the target status (e.g., PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELED).

- timestamp: string (ISO 8601); optional but recommended; time of the requested update.

- reason: string; optional; explanation for the change.

- requesterId: string; optional; identifier of the initiating service or user.

- version or etag: string or integer; optional; for optimistic concurrency control.

- notifyCustomer: boolean; optional; whether to trigger a customer notification.

- metadata: object; optional; additional context or fields.

Validation and semantics

Public APIs typically validate that the order exists, that the transition from the current status to newStatus is allowed, and that required fields are present. Idempotency keys may be used to avoid duplicate updates in retriable environments. On success, the system may apply the change and emit downstream events; on failure, a descriptive error is returned.

Example

{

"orderId": "ORD-12345",

"newStatus": "SHIPPED",

"timestamp": "2025-12-24T12:34:56Z",

"reason": "Fulfillment complete",

"requesterId": "warehouse-service",

"notifyCustomer": true,

"correlationId": "abc-123"

}

See also: UpdateOrderStatusResponse, OrderStatus, IdempotencyKey.