> ## 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. # Execute a configured cancellation retention offer and record the retention activity ## OpenAPI ````yaml /subscription/storefront-api-swagger.json post /subscriptions/cp/api/cancellation-retention-offers/execute 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/cancellation-retention-offers/execute: post: tags: - Subscription Contracts summary: >- Execute a configured cancellation retention offer and record the retention activity operationId: executeCancellationRetentionOffer requestBody: content: application/json: schema: $ref: '#/components/schemas/CancellationRetentionOfferExecuteRequestDTO' required: true responses: '200': content: '*/*': schema: $ref: >- #/components/schemas/CancellationRetentionOfferExecuteResponseDTO description: OK components: schemas: CancellationRetentionOfferExecuteRequestDTO: properties: billingAttemptId: format: int64 type: integer billingInterval: enum: - DAY - WEEK - MONTH - YEAR - $UNKNOWN type: string billingIntervalCount: format: int32 type: integer cancellationReason: type: string compatibleSellingPlanId: type: string contractId: format: int64 type: integer eventSource: enum: - PAUSE - CANCELLATION type: string feedback: type: string flowId: format: int64 type: integer flowReasonId: type: string frequencyKey: type: string nextBillingDate: format: date-time type: string offerTier: type: string pauseDurationCycle: format: int32 type: integer replaceVariantsInfo: $ref: '#/components/schemas/ReplaceVariantsInfoV3' rescheduleFutureOrder: type: boolean retentionAction: format: int32 type: integer sellingPlanId: format: int64 type: integer shippingAddress: $ref: '#/components/schemas/ChangeShippingAddressVM' skipCycle: format: int32 type: integer type: object CancellationRetentionOfferExecuteResponseDTO: properties: cancellationReason: type: string contractId: format: int64 type: integer eventSource: enum: - PAUSE - CANCELLATION type: string retentionAction: format: int32 type: integer retentionActionLabel: type: string retentionActivity: $ref: '#/components/schemas/CustomerRetentionActivityDTO' type: object ReplaceVariantsInfoV3: description: >- Product replacement configuration for subscription contracts. Allows replacing existing subscription products with new ones, managing quantities, and handling one-time purchases. properties: babParentVariantId: description: >- When set, this is treated as a fixed-price Build-a-Box child swap: the numeric variant ID of the parent bundle line whose child products will be replaced. When present, babReplaceSubVariantDetails is applied instead of the line-item variant swap. example: 42549172011164 format: int64 type: integer babReplaceSubVariantDetails: description: >- Old-to-new child variant mappings applied to the parent bundle line's child products when babParentVariantId is set. items: $ref: '#/components/schemas/ReplaceSubVariantDetails' type: array babRequireAllSourceVariants: default: false description: >- When true and babParentVariantId is set, a bundle line is only updated when every oldVariantId from babReplaceSubVariantDetails is present in the box. Default is false (each old-to-new mapping applies independently). example: false type: boolean carryForwardDiscount: description: >- Determines how discounts are applied to new products when replacing variants. If not specified, uses the merchant's default setting. enum: - NONE - EXISTING_PLAN - PRODUCT_PLAN - PRODUCT_THEN_EXISTING - PRODUCT_THEN_EXISTING - PRODUCT_PLAN - EXISTING_PLAN example: PRODUCT_THEN_EXISTING type: string contractId: description: The ID of the subscription contract to modify example: 123456789 format: int64 type: integer eventSource: enum: - CUSTOMER_PORTAL - MERCHANT_PORTAL - SHOPIFY_EVENT - SYSTEM_EVENT - MERCHANT_PORTAL_BULK_AUTOMATION - SCHEDULED_BULK_AUTOMATION - MERCHANT_EXTERNAL_API - SHOPIFY_FLOW type: string newOneTimeVariants: additionalProperties: description: >- Map of one-time product variant IDs to add with their quantities. These products will be charged only once with the next order and won't recur. Useful for add-ons, samples, or limited-time offers. format: int32 type: integer description: >- Map of one-time product variant IDs to add with their quantities. These products will be charged only once with the next order and won't recur. Useful for add-ons, samples, or limited-time offers. example: '42549172066666': 1 '42549172077777': 2 type: object newVariants: additionalProperties: description: >- Map of new variant IDs to their quantities. Key is the numeric Shopify variant ID, value is the desired quantity. If a variant already exists in the subscription and the system is configured to update existing quantities, the quantity will be added to the existing quantity. format: int32 type: integer description: >- Map of new variant IDs to their quantities. Key is the numeric Shopify variant ID, value is the desired quantity. If a variant already exists in the subscription and the system is configured to update existing quantities, the quantity will be added to the existing quantity. example: '42549172033333': 2 '42549172044444': 1 type: object oldLineId: description: >- Specific subscription line ID to replace. Use this for targeted replacement of a single line item. When provided, oldVariants should be empty. Format: gid://shopify/SubscriptionLine/[ID] example: gid://shopify/SubscriptionLine/987654321 type: string oldOneTimeVariants: description: >- List of one-time product variant IDs to remove from the subscription. Only removes one-time products that haven't been fulfilled yet. example: - 42549172055555 - 42549172088888 items: description: >- List of one-time product variant IDs to remove from the subscription. Only removes one-time products that haven't been fulfilled yet. format: int64 type: integer type: array oldVariants: description: >- List of variant IDs to remove from the subscription. These are numeric Shopify variant IDs. Either provide oldVariants OR oldLineId, not both. example: - 42549172011164 - 42549172022222 items: description: >- List of variant IDs to remove from the subscription. These are numeric Shopify variant IDs. Either provide oldVariants OR oldLineId, not both. format: int64 type: integer type: array shop: description: The Shop of the subscription contract to modify example: abcStore.myshopify.com type: string stopSwapEmails: default: false description: >- If true, suppresses email notifications about the product swap. Default is false (emails will be sent). example: false type: boolean required: - contractId - shop type: object ChangeShippingAddressVM: properties: address1: type: string address2: type: string city: type: string company: type: string country: type: string countryCode: type: string firstName: type: string lastName: type: string locationId: type: string methodType: type: string phone: type: string province: type: string provinceCode: type: string zip: type: string type: object CustomerRetentionActivityDTO: properties: activityOn: format: date-time type: string additionalInfo: type: string cancellationReason: type: string contractId: format: int64 type: integer discountApplied: type: string eventSource: enum: - PAUSE - CANCELLATION type: string id: format: int64 type: integer retentionAction: type: string shop: type: string type: object ReplaceSubVariantDetails: description: >- Old-to-new child variant mappings applied to the parent bundle line's child products when babParentVariantId is set. properties: newVariantId: format: int64 type: integer newVariantQuantity: format: int32 type: integer newVariantTitle: type: string oldVariantId: format: int64 type: integer oldVariantQuantity: format: int32 type: integer oldVariantTitle: type: string type: object ````