Subscription Management
Update subscription contract status
Updates the status of a subscription contract to ACTIVE, PAUSED, or CANCELLED. This endpoint manages the lifecycle of subscriptions with automatic state tracking and notifications.
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