> ## 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. # Get cancellation management configuration > Retrieves the cancellation management and retention settings for the authenticated shop. These settings control the subscription cancellation flow, retention strategies, and customer feedback collection when subscribers attempt to cancel their subscriptions. **What is Cancellation Management?** Cancellation management is a retention system that helps merchants reduce subscription churn by understanding why customers cancel and offering alternatives before they leave. It includes cancellation flows, feedback collection, retention offers (discounts, pauses, frequency changes), and automated win-back strategies. **Configuration Components:** **1. Cancellation Flow Settings:** - Enable/disable self-service cancellation in customer portal - Require customer to contact support for cancellation - Multi-step cancellation confirmation process - Cancellation cooldown period (prevent accidental cancellations) - Minimum subscription duration before cancellation allowed - Immediate vs. end-of-billing-cycle cancellation **2. Cancellation Reasons & Feedback:** - Predefined cancellation reasons list - Custom cancellation reason options - Required vs. optional feedback - Free-form text feedback field - Rating/satisfaction scale - Exit survey questions - Feedback sent to merchant email/dashboard **Common Cancellation Reasons:** - Too expensive / Can't afford - Don't use product enough / Have too much inventory - Product quality issues - Switching to competitor - Delivery issues / Shipping problems - Forgot to cancel earlier - Temporary pause needed (moving, travel, etc.) - Product doesn't meet expectations - Customer service issues - Other (with text field) **3. Retention Offers (Save Flow):** - Display retention offers before final cancellation - Offer discount (percentage or fixed amount) - Offer free product/gift with next order - Suggest subscription pause instead of cancel - Suggest frequency change (deliver less often) - Offer to skip next order - Offer to swap products - Personalized offers based on cancellation reason **Example Retention Logic:** ``` Reason: "Too expensive" → Offer: 20% discount for next 3 months → Offer: Switch to smaller/cheaper variant Reason: "Have too much inventory" → Offer: Pause for 1-3 months → Offer: Change from monthly to every 2 months → Offer: Skip next 2 deliveries Reason: "Product quality issues" → Offer: Free replacement on next order → Offer: Try different product variant → Route to customer support ``` **4. UI/UX Configuration:** - Cancellation button placement and styling - Warning messages and modal dialogs - Progress indicator for multi-step flow - Retention offer presentation (modal, inline, etc.) - Confirmation messages - Post-cancellation survey **5. Automation & Notifications:** - Send cancellation confirmation email - Notify merchant of cancellations - Trigger win-back email campaigns - Schedule feedback review - Alert for high cancellation rate - Integration with CRM/analytics tools **6. Metrics & Analytics:** - Track cancellation rate - Categorize cancellation reasons - Measure retention offer acceptance rate - Calculate customer lifetime value at cancellation - Identify churn patterns and trends - A/B test different retention strategies **7. Advanced Features:** - Conditional retention offers based on: - Customer lifetime value - Subscription duration - Product type - Cancellation history - Customer segment - Win-back campaigns for cancelled subscribers - Automatic re-engagement emails (30, 60, 90 days post-cancel) - Special offers to reactivate cancelled subscriptions **Cancellation Flow Examples:** **Basic Flow (No Retention):** 1. Customer clicks "Cancel Subscription" 2. Confirmation dialog: "Are you sure?" 3. Optional: Select cancellation reason 4. Subscription cancelled immediately or at period end 5. Confirmation email sent **Advanced Retention Flow:** 1. Customer clicks "Cancel Subscription" 2. "Before you go..." - Select cancellation reason 3. Display personalized retention offer based on reason 4. Customer chooses: Accept offer OR Continue to cancel 5. If continue: Additional offers or final confirmation 6. If still cancelling: Exit survey 7. Cancellation processed 8. Thank you message + feedback confirmation 9. Follow-up email campaign **Use Cases:** - Configure cancellation flow in customer portal - Customize retention offers and messaging - Analyze cancellation patterns and trends - Build custom cancellation interfaces - Integrate with customer support tools - Generate churn reports and analytics - A/B test different retention strategies - Automate win-back campaigns **Important Notes:** - Always comply with consumer protection laws regarding cancellation - Make cancellation process clear and accessible (FTC guidelines) - Don't make cancellation unnecessarily difficult - Respect customer's decision to cancel - Use retention offers ethically (not dark patterns) - Store cancellation feedback for product improvement - GDPR/privacy compliance for feedback data **Best Practices:** - Keep cancellation process simple (2-3 steps max) - Offer genuine value in retention offers - Personalize offers based on cancellation reason - Make pause/skip options prominent - Use cancellation feedback to improve product/service - Set up automated win-back campaigns - Monitor cancellation rate and take action on trends - Train customer support on retention strategies - Test different retention messaging and offers - Honor cancellations promptly and professionally **Legal & Compliance:** - FTC regulations require easy cancellation (Click-to-Cancel rule) - California automatic renewal law compliance - European consumer protection directives - Clear disclosure of cancellation terms - Process cancellations within legal timeframes - Provide confirmation of cancellation **Authentication:** Requires valid X-API-Key header ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/cancellation-managements/{id} 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/cancellation-managements/{id}: get: tags: - Operations & Settings - Customer Retention summary: Get cancellation management configuration description: >- Retrieves the cancellation management and retention settings for the authenticated shop. These settings control the subscription cancellation flow, retention strategies, and customer feedback collection when subscribers attempt to cancel their subscriptions. **What is Cancellation Management?** Cancellation management is a retention system that helps merchants reduce subscription churn by understanding why customers cancel and offering alternatives before they leave. It includes cancellation flows, feedback collection, retention offers (discounts, pauses, frequency changes), and automated win-back strategies. **Configuration Components:** **1. Cancellation Flow Settings:** - Enable/disable self-service cancellation in customer portal - Require customer to contact support for cancellation - Multi-step cancellation confirmation process - Cancellation cooldown period (prevent accidental cancellations) - Minimum subscription duration before cancellation allowed - Immediate vs. end-of-billing-cycle cancellation **2. Cancellation Reasons & Feedback:** - Predefined cancellation reasons list - Custom cancellation reason options - Required vs. optional feedback - Free-form text feedback field - Rating/satisfaction scale - Exit survey questions - Feedback sent to merchant email/dashboard **Common Cancellation Reasons:** - Too expensive / Can't afford - Don't use product enough / Have too much inventory - Product quality issues - Switching to competitor - Delivery issues / Shipping problems - Forgot to cancel earlier - Temporary pause needed (moving, travel, etc.) - Product doesn't meet expectations - Customer service issues - Other (with text field) **3. Retention Offers (Save Flow):** - Display retention offers before final cancellation - Offer discount (percentage or fixed amount) - Offer free product/gift with next order - Suggest subscription pause instead of cancel - Suggest frequency change (deliver less often) - Offer to skip next order - Offer to swap products - Personalized offers based on cancellation reason **Example Retention Logic:** ``` Reason: "Too expensive" → Offer: 20% discount for next 3 months → Offer: Switch to smaller/cheaper variant Reason: "Have too much inventory" → Offer: Pause for 1-3 months → Offer: Change from monthly to every 2 months → Offer: Skip next 2 deliveries Reason: "Product quality issues" → Offer: Free replacement on next order → Offer: Try different product variant → Route to customer support ``` **4. UI/UX Configuration:** - Cancellation button placement and styling - Warning messages and modal dialogs - Progress indicator for multi-step flow - Retention offer presentation (modal, inline, etc.) - Confirmation messages - Post-cancellation survey **5. Automation & Notifications:** - Send cancellation confirmation email - Notify merchant of cancellations - Trigger win-back email campaigns - Schedule feedback review - Alert for high cancellation rate - Integration with CRM/analytics tools **6. Metrics & Analytics:** - Track cancellation rate - Categorize cancellation reasons - Measure retention offer acceptance rate - Calculate customer lifetime value at cancellation - Identify churn patterns and trends - A/B test different retention strategies **7. Advanced Features:** - Conditional retention offers based on: - Customer lifetime value - Subscription duration - Product type - Cancellation history - Customer segment - Win-back campaigns for cancelled subscribers - Automatic re-engagement emails (30, 60, 90 days post-cancel) - Special offers to reactivate cancelled subscriptions **Cancellation Flow Examples:** **Basic Flow (No Retention):** 1. Customer clicks "Cancel Subscription" 2. Confirmation dialog: "Are you sure?" 3. Optional: Select cancellation reason 4. Subscription cancelled immediately or at period end 5. Confirmation email sent **Advanced Retention Flow:** 1. Customer clicks "Cancel Subscription" 2. "Before you go..." - Select cancellation reason 3. Display personalized retention offer based on reason 4. Customer chooses: Accept offer OR Continue to cancel 5. If continue: Additional offers or final confirmation 6. If still cancelling: Exit survey 7. Cancellation processed 8. Thank you message + feedback confirmation 9. Follow-up email campaign **Use Cases:** - Configure cancellation flow in customer portal - Customize retention offers and messaging - Analyze cancellation patterns and trends - Build custom cancellation interfaces - Integrate with customer support tools - Generate churn reports and analytics - A/B test different retention strategies - Automate win-back campaigns **Important Notes:** - Always comply with consumer protection laws regarding cancellation - Make cancellation process clear and accessible (FTC guidelines) - Don't make cancellation unnecessarily difficult - Respect customer's decision to cancel - Use retention offers ethically (not dark patterns) - Store cancellation feedback for product improvement - GDPR/privacy compliance for feedback data **Best Practices:** - Keep cancellation process simple (2-3 steps max) - Offer genuine value in retention offers - Personalize offers based on cancellation reason - Make pause/skip options prominent - Use cancellation feedback to improve product/service - Set up automated win-back campaigns - Monitor cancellation rate and take action on trends - Train customer support on retention strategies - Test different retention messaging and offers - Honor cancellations promptly and professionally **Legal & Compliance:** - FTC regulations require easy cancellation (Click-to-Cancel rule) - California automatic renewal law compliance - European consumer protection directives - Clear disclosure of cancellation terms - Process cancellations within legal timeframes - Provide confirmation of cancellation **Authentication:** Requires valid X-API-Key header operationId: getCancellationManagementV2 parameters: - in: path name: id required: true schema: format: int64 type: integer - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string responses: '200': content: application/json: examples: Success Response: description: Success Response value: allowCustomReason: true allowSelfServiceCancellation: true analytics: alertOnHighChurnRate: true churnRateThreshold: 15 trackCancellationRate: true trackReasonFrequency: true trackRetentionOfferAcceptance: true cancellationReasons: - Too expensive - Have too much product - Product quality issues - Switching to competitor - Delivery problems - Don't need anymore - Temporary situation (moving, travel, etc.) - Other cancellationTiming: END_OF_BILLING_CYCLE collectFeedback: true confirmationFlow: cooldownPeriod: 24 multiStep: true requireConfirmation: true showAlternatives: true createdAt: '2024-01-15T10:30:00Z' enabled: true feedbackRequired: false id: 12345 minimumSubscriptionDays: 30 notifications: enableCampaigns: true merchantEmail: subscriptions@example.com sendCustomerConfirmation: true sendMerchantNotification: true winBackSchedule: - 30 - 60 - 90 requireCancellationReason: true requireSupportContact: false retentionOffersEnabled: true retentionStrategies: Have too much product: - description: Pause for up to 3 months maxDuration: 90 type: PAUSE - description: Skip your next 2 deliveries skipCount: 2 type: SKIP - description: Switch to every 2 months type: FREQUENCY_CHANGE Product quality issues: - description: Let us make it right - contact support type: SUPPORT_CONTACT - description: Try a different product type: PRODUCT_SWAP Too expensive: - description: 20% off for 3 months duration: 3 type: DISCOUNT value: '20' - description: Deliver less often to save money type: FREQUENCY_CHANGE shop: example-shop.myshopify.com showExitSurvey: true uiSettings: buttonColor: '#DC3545' buttonText: Cancel Subscription confirmationMessage: >- Your subscription has been cancelled. You will receive a confirmation email shortly. thankYouMessage: >- Thank you for being a subscriber. We hope to see you again! warningMessage: >- We'll be sorry to see you go! Before you cancel, let us try to help. updatedAt: '2024-02-20T14:45:00Z' schema: $ref: '#/components/schemas/CancellationManagementDTO' description: Cancellation management configuration successfully retrieved '401': content: application/json: example: detail: Valid X-API-Key header is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required '403': content: application/json: example: detail: >- API key does not have permission to view cancellation management settings status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to view cancellation management settings '404': content: application/json: example: detail: Cancellation management has not been configured for this shop status: 404 title: Configuration not found type: https://example.com/errors/not-found description: Cancellation management configuration not found components: schemas: CancellationManagementDTO: properties: cancellationInstructionsText: type: string cancellationReasonsJSON: type: string cancellationType: enum: - CANCEL_IMMEDIATELY - CANCELLATION_INSTRUCTIONS - CUSTOMER_RETENTION_FLOW - CANCEL_AFTER_PAUSE type: string discountEmailAddress: type: string dynamicallyPauseCycleOnCancellation: type: boolean enableDiscountEmail: type: boolean id: format: int64 type: integer pauseDurationCycle: format: int32 type: integer pauseInstructionsText: type: string pauseReasonsJSON: type: string pauseType: enum: - PAUSE_IMMEDIATELY - PAUSE_INSTRUCTIONS - CUSTOMER_RETENTION_FLOW type: string shop: type: string required: - shop type: object ````