Update order

Update specific fields of an existing order with HMAC signature verification and idempotency protection.

🔐 HMAC Signing (REQUIRED)

All order update requests MUST include HMAC-SHA256 signature:

1. Generate Timestamp: Get current Unix timestamp in seconds
2. Create Payload: Concatenate timestamp + "." + JSON_body
3. Sign Payload: HMAC-SHA256(hmac_secret, payload) → base64 encode
4. Include Headers:
   • X-Timestamp: Unix timestamp (must be within 5 minutes)
   • X-Signature: Base64-encoded HMAC signature

🔄 Idempotency Protection

Include Idempotency-Key header to prevent duplicate updates on retry. Each PATCH operation is tracked separately - if you retry with the same key, the original order state is returned without re-processing side effects.

Important: Use a unique idempotency key for each distinct update operation.

• ✅ Good: update-shipping-{order_id}-{timestamp}, mark-paid-{order_id}-{timestamp}
• ❌ Bad: Reusing the same key for different updates to the same order

This prevents duplicate processing of critical operations like:

• Double-triggering accounting entries when marking as paid
• Re-reducing inventory stock
• Duplicate gift card redemptions
• Multiple promotion usage recordings

Updatable Fields:

• payment_status: Payment status (pending, paid, failed, refunded)
• order_status: Order fulfillment status (pending, processing, shipped, delivered, cancelled)
• notes: Additional order notes
• tracking_number: Shipping tracking number
• estimated_delivery: Estimated delivery date/time
• shipped_at: Timestamp when order was shipped
• delivered_at: Timestamp when order was delivered

Automatic Accounting: When payment_status is updated to paid, the system automatically:

• Triggers accounting entry creation (production only)
• Reduces inventory stock for all order items
• Updates customer purchase metrics
• Processes gift card redemptions (if applicable)
• Records promotion usage (if applicable)

Key Type Support:

• ✅ Secret keys (full access)
• ❌ Publishable keys (forbidden - returns 403)