> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription retention API

> Read recovered revenue, at-risk subscriptions and the saved-subscriptions report, and configure recovery, save offers and intro pricing with an API key.

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

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

```json theme={"system"}
{
  "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

```bash theme={"system"}
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

```bash theme={"system"}
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](/api-webhooks/events#subscription-payment-failed)
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.