# Order status changed event

Sent when any of the order's three status fields change (lifecycle
status, fulfillment status, or payment status). Includes previous
and current values for all three fields.

Endpoint: POST order-status-changed
Version: 1.0.0
Security: 

## Request fields (application/json):

  - `event_id` (string, required)
    Unique identifier for this event. Use for idempotent processing.

  - `event_type` (string, required)
    The type of event that occurred. Determines the shape of the data field.

  - `created_at` (string, required)
    When the event occurred (ISO 8601 UTC).

  - `data` (object, required)
    Event-specific payload. Shape depends on event_type.
See individual event schemas for details.

  - `data.order_id` (string, required)
    Unique identifier for the order.

  - `data.location_id` (string, required)
    The location (store) this order belongs to.

  - `data.previous_status` (string, required)
    Order lifecycle status. Tracks the high-level state of the order from
creation through completion or cancellation.

- PENDING: Order created from cart checkout, awaiting payment.
- CONFIRMED: At least one payment completed; order accepted by the store.
- COMPLETED: Order fulfilled and closed.
- FAILED: Order could not be processed (e.g., all payments failed).
- VOIDED: Order voided before any fulfillment began.
- CANCELLED: Order cancelled by customer or system.

State transitions:
- PENDING -> CONFIRMED, FAILED, VOIDED, CANCELLED
- CONFIRMED -> COMPLETED, CANCELLED
- COMPLETED, FAILED, VOIDED, CANCELLED are terminal (no further transitions)
    Enum: "PENDING", "CONFIRMED", "COMPLETED", "FAILED", "VOIDED", "CANCELLED"

  - `data.current_status` (string, required)
    Order lifecycle status. Tracks the high-level state of the order from
creation through completion or cancellation.

- PENDING: Order created from cart checkout, awaiting payment.
- CONFIRMED: At least one payment completed; order accepted by the store.
- COMPLETED: Order fulfilled and closed.
- FAILED: Order could not be processed (e.g., all payments failed).
- VOIDED: Order voided before any fulfillment began.
- CANCELLED: Order cancelled by customer or system.

State transitions:
- PENDING -> CONFIRMED, FAILED, VOIDED, CANCELLED
- CONFIRMED -> COMPLETED, CANCELLED
- COMPLETED, FAILED, VOIDED, CANCELLED are terminal (no further transitions)
    Enum: "PENDING", "CONFIRMED", "COMPLETED", "FAILED", "VOIDED", "CANCELLED"

  - `data.previous_fulfillment_status` (string, required)
    Fulfillment lifecycle status. Tracks the physical preparation and handoff
of the order. Maps directly from the backend fulfillment state machine.

- PENDING: Order created, not yet accepted by store.
- IN_PROGRESS: Store accepted the order and is queuing it.
- PREPARING: Store staff actively assembling the order.
- READY_FOR_PICKUP: Order assembled and waiting for customer (pickup/curbside).
- FULFILLED: Customer received the order (pickup/curbside/kiosk).
- DELIVERED: Order delivered to customer address (delivery orders).
- RETURNED: Order returned after fulfillment.
- CANCELLED: Fulfillment cancelled before completion.

State transitions:
- PENDING -> IN_PROGRESS, CANCELLED
- IN_PROGRESS -> PREPARING, CANCELLED
- PREPARING -> READY_FOR_PICKUP, CANCELLED
- READY_FOR_PICKUP -> FULFILLED, DELIVERED, CANCELLED
- FULFILLED -> RETURNED
- DELIVERED -> RETURNED
- RETURNED, CANCELLED are terminal (no further transitions)

Cancellation restriction: Orders can only be cancelled via
POST /orders/{order_id}/cancel when fulfillment_status is PENDING or
IN_PROGRESS. Once preparation begins, cancellation requires store
intervention.
    Enum: "PENDING", "IN_PROGRESS", "PREPARING", "READY_FOR_PICKUP", "FULFILLED", "DELIVERED", "RETURNED", "CANCELLED"

  - `data.current_fulfillment_status` (string, required)
    Fulfillment lifecycle status. Tracks the physical preparation and handoff
of the order. Maps directly from the backend fulfillment state machine.

- PENDING: Order created, not yet accepted by store.
- IN_PROGRESS: Store accepted the order and is queuing it.
- PREPARING: Store staff actively assembling the order.
- READY_FOR_PICKUP: Order assembled and waiting for customer (pickup/curbside).
- FULFILLED: Customer received the order (pickup/curbside/kiosk).
- DELIVERED: Order delivered to customer address (delivery orders).
- RETURNED: Order returned after fulfillment.
- CANCELLED: Fulfillment cancelled before completion.

State transitions:
- PENDING -> IN_PROGRESS, CANCELLED
- IN_PROGRESS -> PREPARING, CANCELLED
- PREPARING -> READY_FOR_PICKUP, CANCELLED
- READY_FOR_PICKUP -> FULFILLED, DELIVERED, CANCELLED
- FULFILLED -> RETURNED
- DELIVERED -> RETURNED
- RETURNED, CANCELLED are terminal (no further transitions)

Cancellation restriction: Orders can only be cancelled via
POST /orders/{order_id}/cancel when fulfillment_status is PENDING or
IN_PROGRESS. Once preparation begins, cancellation requires store
intervention.
    Enum: "PENDING", "IN_PROGRESS", "PREPARING", "READY_FOR_PICKUP", "FULFILLED", "DELIVERED", "RETURNED", "CANCELLED"

  - `data.previous_payment_status` (string, required)
    Aggregate payment status across all payments on the order. This is a
server-computed summary -- do not set directly.

- UNPAID: No payments submitted yet.
- PROCESSING: At least one payment is in a non-terminal state (PENDING or AUTHORIZED).
- PARTIALLY_PAID: Some payments completed but total paid = order total. The order is fully covered.

State transitions:
- UNPAID -> PROCESSING, PARTIALLY_PAID, PAID
- PROCESSING -> PARTIALLY_PAID, PAID, UNPAID (if all payments fail)
- PARTIALLY_PAID -> PROCESSING, PAID
- PAID is terminal for forward flow (refunds revert to PARTIALLY_PAID or UNPAID)
    Enum: "UNPAID", "PROCESSING", "PARTIALLY_PAID", "PAID"

  - `data.current_payment_status` (string, required)
    Aggregate payment status across all payments on the order. This is a
server-computed summary -- do not set directly.

- UNPAID: No payments submitted yet.
- PROCESSING: At least one payment is in a non-terminal state (PENDING or AUTHORIZED).
- PARTIALLY_PAID: Some payments completed but total paid = order total. The order is fully covered.

State transitions:
- UNPAID -> PROCESSING, PARTIALLY_PAID, PAID
- PROCESSING -> PARTIALLY_PAID, PAID, UNPAID (if all payments fail)
- PARTIALLY_PAID -> PROCESSING, PAID
- PAID is terminal for forward flow (refunds revert to PARTIALLY_PAID or UNPAID)
    Enum: "UNPAID", "PROCESSING", "PARTIALLY_PAID", "PAID"

  - `data.updated_at` (string, required)
    When the status change occurred.


## Response 200 fields