> ## 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 customer retention activities > Retrieves a paginated, filterable list of customer retention activities for the authenticated shop. A retention activity is recorded whenever a customer goes through the cancellation or pause flow and either accepts a retention offer (discount, pause, frequency change, product swap, etc.) or proceeds to cancel/pause, along with the reason they selected. **What is a Retention Activity?** Every time a subscriber interacts with the cancellation/pause save-flow, an activity record is created capturing the contract, the action taken (e.g. offer shown, offer accepted, cancelled, paused), the event source (CANCELLATION or PAUSE), the selected reason, any discount applied, and the resulting status. **Filtering:** - `contractId` - restrict results to a single subscription contract - `eventSource` - `CANCELLATION` or `PAUSE` - `status` - status of the retention activity (e.g. PENDING, COMPLETED) - `retentionAction` - the action recorded (e.g. offer type accepted or DECLINED) - `retentionReason` - the cancellation/pause reason the customer selected - `fromDay` / `toDay` - ISO-8601 date-time bounds on `activityOn` **Pagination:** Standard Spring pagination parameters are supported: `page` (0-indexed), `size`, and `sort` (e.g. `sort=id,desc`). Pagination metadata (total count, total pages, link headers) is returned in the response headers. **Use Cases:** - Build custom churn/retention dashboards and reports - Sync retention activity into an external CRM or data warehouse - Audit which retention offers are converting for a given contract or reason - Feed win-back campaign automation with recent cancellation reasons **Authentication:** Requires a valid API key, passed via the `X-API-Key` header (preferred) or the `api_key` query parameter (deprecated). ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/customer-retention-activities 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/customer-retention-activities: get: tags: - Customer Retention summary: Get customer retention activities description: >- Retrieves a paginated, filterable list of customer retention activities for the authenticated shop. A retention activity is recorded whenever a customer goes through the cancellation or pause flow and either accepts a retention offer (discount, pause, frequency change, product swap, etc.) or proceeds to cancel/pause, along with the reason they selected. **What is a Retention Activity?** Every time a subscriber interacts with the cancellation/pause save-flow, an activity record is created capturing the contract, the action taken (e.g. offer shown, offer accepted, cancelled, paused), the event source (CANCELLATION or PAUSE), the selected reason, any discount applied, and the resulting status. **Filtering:** - `contractId` - restrict results to a single subscription contract - `eventSource` - `CANCELLATION` or `PAUSE` - `status` - status of the retention activity (e.g. PENDING, COMPLETED) - `retentionAction` - the action recorded (e.g. offer type accepted or DECLINED) - `retentionReason` - the cancellation/pause reason the customer selected - `fromDay` / `toDay` - ISO-8601 date-time bounds on `activityOn` **Pagination:** Standard Spring pagination parameters are supported: `page` (0-indexed), `size`, and `sort` (e.g. `sort=id,desc`). Pagination metadata (total count, total pages, link headers) is returned in the response headers. **Use Cases:** - Build custom churn/retention dashboards and reports - Sync retention activity into an external CRM or data warehouse - Audit which retention offers are converting for a given contract or reason - Feed win-back campaign automation with recent cancellation reasons **Authentication:** Requires a valid API key, passed via the `X-API-Key` header (preferred) or the `api_key` query parameter (deprecated). operationId: getAllCustomerRetentionActivitiesExternal parameters: - 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 - in: query name: contractId required: false schema: format: int64 type: integer - in: query name: eventSource required: false schema: enum: - PAUSE - CANCELLATION type: string - in: query name: status required: false schema: type: string - in: query name: retentionAction required: false schema: type: string - in: query name: retentionReason required: false schema: type: string - in: query name: fromDay required: false schema: format: date-time type: string - in: query name: toDay required: false schema: format: date-time type: string - description: Pagination parameters (page number and size) example: page: 0 size: 10 sort: - id,desc in: query name: pageable required: true schema: $ref: '#/components/schemas/Pageable' responses: '200': content: application/json: examples: Success Response: description: Success Response value: - activityOn: '2026-08-01T14:22:10Z' additionalInfo: '{"offerId":"disc_20pct"}' cancellationReason: Too expensive contractId: 991823 customerEmail: jane.doe@example.com customerName: Jane Doe discountApplied: 20% off for 3 months eventSource: CANCELLATION id: 4821 retentionAction: DISCOUNT_ACCEPTED shop: example-shop.myshopify.com status: COMPLETED schema: items: $ref: '#/components/schemas/CustomerRetentionActivityResponse' type: array description: Customer retention activities 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 customer retention activities status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to view customer retention activities components: schemas: Pageable: properties: page: format: int32 minimum: 0 type: integer size: format: int32 minimum: 1 type: integer sort: items: type: string type: array type: object CustomerRetentionActivityResponse: properties: activityOn: type: string additionalInfo: type: string cancellationReason: type: string contractId: format: int64 type: integer customerEmail: type: string customerName: type: string discountApplied: type: string eventSource: enum: - PAUSE - CANCELLATION type: string id: format: int64 type: integer retentionAction: type: string shop: type: string status: type: string type: object ````