Subscription retention API

The retention endpoints live under /subscription-retention. They use your API key like every other endpoint and work in the key’s mode (live or test). Reads are open on every plan; writes that turn a feature on need the Pro plan and otherwise answer 403 with code: "FEATURE_LOCKED" and details.requiredPlan. Turning a feature off is always allowed.

Method	Path	What it does
`GET`	`/subscription-retention/recovery/summary?days=30`	Recovered revenue, at-risk amount, recovery rate
`GET`	`/subscription-retention/recovery/at-risk?status=open`	Failed renewals (`open`, `recovered` or `closed`), paginated
`GET`	`/subscription-retention/recovery/settings`	Recovery settings
`PUT`	`/subscription-retention/recovery/settings`	Change `enabled`, `finalAction`, `emailBuyer`
`GET`	`/subscription-retention/save-offers/report?days=30`	Saved subscriptions, reasons, recent flows
`GET`	`/subscription-retention/intro/report`	Intro pricing and yearly switch counts
`GET`	`/subscription-retention/offers`	Retention settings of every subscription offer
`GET`	`/subscription-retention/offers/{id}`	One offer’s settings
`PUT`	`/subscription-retention/offers/{id}`	Change `saveOffers`, `intro`, `yearlySwitch`

Money is decimal major units (29.99), never cents. Amounts are reported per currency and never summed across currencies.

Recovery summary

curl https://api.pocketsflow.com/subscription-retention/recovery/summary?days=30 \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY"

{
  "days": 30,
  "recovered": [{ "currency": "usd", "amount": 412, "count": 9 }],
  "recoveredCount": 9,
  "atRisk": [{ "currency": "usd", "amount": 87, "count": 3 }],
  "atRiskCount": 3,
  "lostCount": 2,
  "recoveryRate": 81.8,
  "entitlement": { "allowed": true, "requiredPlan": "tier3" }
}

Recovery settings

curl -X PUT https://api.pocketsflow.com/subscription-retention/recovery/settings \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "finalAction": "pause" }'

finalAction is what happens one day after the last retry (day 7) when the renewal is still unpaid: cancel, pause (the unpaid renewal is voided, access is kept) or keep.

Per-offer settings

curl -X PUT https://api.pocketsflow.com/subscription-retention/offers/665f1c2a9b3e4a0012ab34cd \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "saveOffers": { "enabled": true, "pauseMaxMonths": 2, "discountPercent": 30, "discountMonths": 3 },
    "intro": { "enabled": true, "price": 1, "periods": 1 },
    "yearlySwitch": { "enabled": true, "afterPayments": 3, "percentOff": 15 }
  }'

Field	Rules
`saveOffers.pauseMaxMonths`	1–3
`saveOffers.discountPercent`	5–90, whole numbers
`saveOffers.discountMonths`	1–12 payments
`intro.price`	at least `1.00` and lower than the regular price; not with a free trial
`intro.periods`	1–12
`yearlySwitch.afterPayments`	1–24; monthly offers only
`yearlySwitch.percentOff`	1–50

An invalid value answers 400 with code: "INVALID_RETENTION_CONFIG", a readable message and the offending field (for example intro.price).

Events

Event	When
`subscription.payment_failed`	A renewal failed and recovery started, and on each later failed attempt
`subscription.recovered`	A failed renewal was paid after all
`subscription.saved`	A subscriber accepted a pause or a discount instead of canceling

Payloads are on the webhook events page. In MCP the same operations are the tools get_recovery_summary, list_at_risk_subscriptions, get_recovery_settings, update_recovery_settings, get_save_offers_report, get_intro_pricing_report, list_retention_offers, get_retention_offer and update_retention_offer.

Overview

API reference

Node.js SDK

Webhooks

Recovery summary

Recovery settings

Per-offer settings

Events

​Recovery summary

​Recovery settings

​Per-offer settings

​Events

Recovery summary

Recovery settings

Per-offer settings

Events