update_retention_settings
Change a project's Revenue Recovery settings — the grace window, the daily digest, the cancellation question and the three offers. Only the arguments present move; null clears an offer. Emits nothing.
Change how a project handles a failed renewal and a cancelling member without restating the
settings: every argument is optional and the row keeps its stored value for each one left out, the
way the REST PUT behaves. The window and the coupons are checked by the same service the dashboard
relies on, answered as VALIDATION_FAILED.
Synchronous — the settings after the change come back. Nothing is announced: the settings are the creator's own, and no webhook event carries them.
Omit to keep, send null to clear
Leaving an argument out leaves it alone. offer_discount_coupon_id: null and
offer_return_coupon_id: null clear the two coupon offers; a coupon must be one of the project's
own.
The offers need the plan, but are stored on every plan
offer_pause_enabled and the two coupons are accepted on every plan and ignored by the
cancellation screen until the project owner's plan includes the offers (Growth or the Revenue
Recovery Addon), which offers_available in the answer says. Switching an offer on early is not
refused and starts working the day the plan includes it.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
Sending the same arguments twice changes nothing the second time.
Arguments
project_id*stringUUID of the project whose Revenue Recovery settings to change.
grace_daysintegeroptionalHow many days a failed renewal keeps the member's access while the gateway retries, 0 to 30. 0 pauses access at the failure.
0max30digest_enabledbooleanoptionalWhether the owner gets one message a day with the failures, reminders, pauses and recoveries, only on a day something happened.
cancel_feedback_enabledbooleanoptionalWhether the cancellation screen asks the member why before the offer. Off skips straight to the offer.
offer_pause_enabledbooleanoptionalWhether a cancelling member whose gateway can hold the charge is offered one billing cycle on hold.
offer_discount_coupon_idstring | nulloptionalUUID of one of the project's coupons, applied to a cancelling member's renewals where the gateway can carry it; null for no discount offer.
offer_return_coupon_idstring | nulloptionalUUID of one of the project's coupons, handed to a cancelling member on the way out on every payment method; null for no return coupon.
What it returns
{ "data": { "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "grace_days": 10, "ladder": "A failed renewal keeps the member's access for 10 days: they are told at once with a link to settle the payment, reminded on day 3 and the day before the window closes, and paused when it does; access comes back by itself with the next successful payment.", "digest_enabled": true, "cancel_feedback_enabled": true, "offers_available": true, "offer_pause_enabled": true, "offer_discount_coupon": { "id": "3b7c9d1e-5f24-4a86-9c0b-2d4e6f8a1b3c", "code": "STAY20" }, "offer_return_coupon": null, "updated_at": "2026-10-12T09:05:00+00:00" }}How it fails
VALIDATION_FAILEDgrace_days outside 0..30, or a coupon that is not one of the project's own.
RESOURCE_NOT_FOUNDunknown project_id, or the project is outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-subscription:update.
How is this guide?
Last updated on
list_retention_activity
List a project's Revenue Recovery ledger — one row per notice, offer, feedback and win-back message, with the member, the channel, and whether a charge settled afterwards. Read-only. Paginated, narrowed by kind.
Role & Group Tools
A role is the permission set one collaborator holds; a group is a bundle several collaborators share.