Get customer retention activities
Retrieves a paginated, filterable list of customer retention activities for the authenticated shop, newest first. A retention activity is recorded when a customer goes through the cancellation or pause flow in the customer portal: the reason they picked, the note they typed and, when they accepted one, the retention offer.
What is a Retention Activity?
Each record captures the contract, the action taken (retentionAction, a numeric code), the event source (CANCELLATION or PAUSE), the reason the customer picked and their note (both inside additionalInfo), any discount applied, and the contract’s current status. A cancellation or pause without an offer is recorded with action 0. Cancelling or pausing a subscription through the Admin API, or through the Storefront API’s cancel and pause endpoints, records nothing.
First offer vs fallback offer:
When the selected cancellation reason has a fallback offer, an accepted offer’s additionalInfo JSON carries offerTier: PRIMARY if the customer accepted the first offer, FALLBACK if they declined it and accepted the fallback. It is absent for reasons without a fallback offer, for declines, and for activities recorded before this field was introduced.
Dates:
fromDay and toDay are both optional. Send them as ISO-8601 date-times such as 2026-11-01T00:00:00Z. Leave both out to get every record, or send only one for an open-ended period. A date without a time returns 400.
Filtering:
contractId- restrict results to a single subscription contracteventSource-CANCELLATIONorPAUSEstatus- the subscription contract’s current status, for exampleactive,pausedorcancelledretentionAction- one action code:0none,1discount,2swap,3gift,4skip,5change date,6change address,7update frequency,8pause,9free gift. New offer types get new codes.retentionReason- the reason the customer picked (additionalInfo.actionOption) or the note they typed (additionalInfo.cancellationFeedback), word for wordfromDay/toDay- optional ISO-8601 date-time bounds onactivityOn, both inclusive
Pagination:
Use page (0-indexed) and size (default 20). The total number of matching records is returned in the x-total-count header. The list is always newest first (highest id first). A sort parameter is ignored. The link header holds the URLs of the first and last pages, and of the next and previous pages when they exist. They keep the encoding of your call, so you can follow them as they are, or build the next page yourself with the same parameters and the next page number.
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).
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/customer-retention-activitiesimport requests
url = "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body[
{
"activityOn": "2026-11-04 04:03:20.0",
"additionalInfo": "{\"actionOption\":\"Too expensive\",\"cancellationFeedback\":\"It is too expensive right now\"}",
"cancellationReason": "It is too expensive right now",
"contractId": 123456789012,
"customerEmail": "jane.doe@example.com",
"customerName": "Jane Doe",
"discountApplied": null,
"eventSource": "CANCELLATION",
"id": 4821,
"retentionAction": "0",
"shop": "example-shop.myshopify.com",
"status": "active"
}
]{
"detail": "Unexpected runtime exception",
"message": "error.http.400",
"path": "/api/external/v2/customer-retention-activities",
"status": 400,
"title": "Bad Request",
"type": "https://appstle.com/problem/problem-with-message"
}{
"error": "Unauthorized",
"path": "/api/external/v2/customer-retention-activities",
"status": 401,
"timestamp": "2026-11-04T04:38:45.443+00:00"
}Query Parameters
Response
Customer retention activities successfully retrieved
A JSON string, so parse it. actionOption is the reason the customer picked and cancellationFeedback is their note (- or null when they wrote none); both are missing when the customer picked no reason. It can also hold reasonId, offerTier (PRIMARY or FALLBACK), pauseDurationCycle and skipDurationCycle, discountCode and discountType for action 1, and freeGiftVariantId and freeGiftTitle for action 9. Accept keys you don't recognize.
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/customer-retention-activitiesimport requests
url = "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/customer-retention-activities")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body[
{
"activityOn": "2026-11-04 04:03:20.0",
"additionalInfo": "{\"actionOption\":\"Too expensive\",\"cancellationFeedback\":\"It is too expensive right now\"}",
"cancellationReason": "It is too expensive right now",
"contractId": 123456789012,
"customerEmail": "jane.doe@example.com",
"customerName": "Jane Doe",
"discountApplied": null,
"eventSource": "CANCELLATION",
"id": 4821,
"retentionAction": "0",
"shop": "example-shop.myshopify.com",
"status": "active"
}
]{
"detail": "Unexpected runtime exception",
"message": "error.http.400",
"path": "/api/external/v2/customer-retention-activities",
"status": 400,
"title": "Bad Request",
"type": "https://appstle.com/problem/problem-with-message"
}{
"error": "Unauthorized",
"path": "/api/external/v2/customer-retention-activities",
"status": 401,
"timestamp": "2026-11-04T04:38:45.443+00:00"
}