> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ## OpenAPI ````yaml /subscription/storefront-api-swagger.json put /subscriptions/cp/api/subscription-contracts-update-status openapi: 3.0.1 info: description: >- Comprehensive API documentation for the customer-facing subscription portal. These APIs enable customers to manage their subscriptions, update billing information, modify delivery schedules, and access their account details through your storefront. **Important**: These APIs must be called from your shop's domain (e.g., https://www.myshop.com/apps/subscriptions/cp/api/**) and require customer authentication. Unauthenticated requests will return a 401 Unauthorized error. title: Storefront APIs version: 0.0.1 servers: - url: https://www.myshop.com/apps security: [] tags: - description: >- Core customer portal APIs for managing customer account settings, authentication, and portal configurations. name: Customer Portal - description: >- APIs for customers to view and manage their subscription contracts including status updates, frequency changes, and cancellations. name: Subscription Management - description: >- APIs for retrieving and updating subscription contract details — delivery schedules, line items, addresses, billing cycles. name: Subscription Contracts - description: >- APIs for retrieving available subscription plans and selling plan configurations exposed to customers. name: Subscription Plans - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for retrieving aggregated subscription data and account-level subscription information for the signed-in customer. name: Subscription Data - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing payment methods, billing information, and processing subscription payments. name: Billing & Payments - description: >- APIs for retrieving product information, selling plans, variant data, and subscription-enabled products available to customers. name: Product Catalog - description: >- APIs for managing delivery schedules, shipping addresses, delivery methods, and tracking order status. name: Delivery & Shipping - description: >- APIs for handling subscription cancellations, retention activities, and customer feedback management. name: Customer Retention - description: >- APIs for integrating loyalty programs with subscriptions including points redemption and earning options. name: Loyalty Integration - description: >- APIs for accessing portal customization settings, translations, and theme configurations. name: Customization - description: >- APIs for retrieving promotional campaigns shown in the customer portal, tracking banner engagement, and redeeming campaign offers. name: Campaigns - description: >- APIs for local pickup and click-and-collect — listing pickup locations and resolving eligible pickup dates and time slots. name: Store Pickup paths: /subscriptions/cp/api/subscription-contracts-update-status: put: tags: - Subscription Management - Subscription Contracts summary: Update subscription contract status description: >- 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 operationId: updateStatus parameters: - in: query name: contractId required: true schema: format: int64 type: integer - in: query name: status required: true schema: type: string - in: query name: pauseDurationCycle required: false schema: format: int32 type: integer - in: query name: pauseFeedback required: false schema: type: string - in: query name: pauseReason required: false schema: type: string responses: '204': content: '*/*': schema: type: string description: Status successfully updated - No content returned headers: X-Alert: description: Success message schema: example: Subscription Updated type: string style: simple '400': content: application/json: examples: Contract Not Found: description: Contract Not Found value: detail: Subscription contract with ID 123456789 not found status: 400 title: No contract found for status update type: https://example.com/errors/bad-request Invalid Contract ID: description: Invalid Contract ID value: detail: Contract ID must be a positive number status: 400 title: Invalid contract ID type: https://example.com/errors/bad-request Invalid Status Value: description: Invalid Status Value value: detail: 'Status must be one of: ACTIVE, PAUSED, CANCELLED' status: 400 title: UserGeneratedError:Invalid subscription status type: https://example.com/errors/bad-request Reactivate Cancelled Subscription: description: Reactivate Cancelled Subscription value: detail: >- Cancelled subscriptions cannot be reactivated. Please create a new subscription. status: 400 title: >- UserGeneratedError:Cannot reactivate cancelled subscription type: https://example.com/errors/bad-request Same Status Update: description: Same Status Update value: detail: Subscription is already ACTIVE. No update needed. status: 400 title: Contract already in same status type: https://example.com/errors/bad-request description: Invalid request parameters or business rule violation '401': content: application/json: example: detail: Valid API key is required to access this endpoint status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required - missing or invalid API key '403': content: application/json: examples: API Key Permissions: description: API Key Permissions value: detail: >- API key does not have permission to modify subscription contracts status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden Customer Portal - Pause Permission: description: Customer Portal - Pause Permission value: detail: Customer does not have permission to pause subscriptions status: 403 title: Customer permission denied type: https://example.com/errors/forbidden description: Insufficient permissions to modify subscription status '404': content: application/json: example: detail: >- Subscription contract with ID 123456789 not found in the system status: 404 title: Resource not found type: https://example.com/errors/not-found description: Subscription contract not found '422': content: application/json: examples: Invalid Discount Code: description: Invalid Discount Code value: detail: >- Invalid discount code detected. System will automatically remove and retry. status: 422 title: Contract draft discount with title SUMMER20 is invalid type: https://example.com/errors/unprocessable-entity Shopify API Error: description: Shopify API Error value: detail: >- Shopify API error: Cannot modify subscription during active billing attempt status: 422 title: UserGeneratedError:Unable to update subscription status type: https://example.com/errors/unprocessable-entity description: Unable to process the status update due to Shopify API constraints ````