Update subscription contract status

Status Transitions:

• ACTIVE: Resumes a paused subscription, enabling future billing and deliveries
• PAUSED: Temporarily suspends all billing and deliveries until manually resumed
• CANCELLED: Permanently terminates the subscription (irreversible)

Key Features:

• Validates status transitions (prevents same-status updates)
• Tracks status change timestamps for audit trails
• Sends automated email notifications to customers
• Creates detailed activity logs for each status change
• Handles concurrent modifications with automatic retry
• Adjusts next billing date when resuming subscriptions

Permission Requirements (Customer Portal): When called from customer portal context:

• PAUSED status requires ‘pauseResumeSub’ permission
• ACTIVE status (resuming) requires ‘resumeSub’ permission
• CANCELLED status requires ‘cancelSub’ permission
• External API calls bypass these permission checks

Status Change Side Effects:

• Activating: Recalculates next billing date, marks activation timestamp
• Pausing: Stops all scheduled orders, marks pause timestamp
• Cancelling: Terminates subscription permanently, marks cancellation timestamp

Error Recovery: The system automatically handles:

• Invalid discount codes by removing them and retrying
• Concurrent modifications by retrying the operation
• This ensures reliable status updates in production environments

Important Notes:

• Status values are case-insensitive
• Cancelled subscriptions cannot be reactivated
• Paused subscriptions retain all settings and can be resumed
• Email notifications are sent automatically unless internally suppressed

Authentication: Requires valid X-API-Key header