> ## 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/admin-api-swagger.json put /api/external/v2/subscription-contracts-update-status openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - 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 managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/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: updateStatusV2 parameters: - description: >- Subscription contract ID to update. Provide the numeric ID without the gid:// prefix example: 123456789 in: query name: contractId required: true schema: format: int64 minimum: 1 type: integer - description: New status for the subscription contract. Case-insensitive. examples: Cancel subscription: description: Cancel subscription value: CANCELLED Pause subscription: description: Pause subscription value: PAUSED Resume subscription: description: Resume subscription value: ACTIVE in: query name: status required: true schema: enum: - ACTIVE - PAUSED - CANCELLED - active - paused - cancelled type: string - deprecated: true description: API Key (Deprecated - Use X-API-Key header instead) in: query name: api_key required: false schema: type: string - description: API Key for authentication example: sk_live_1234567890abcdef in: header name: X-API-Key required: true schema: type: string responses: '204': 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 ````