Version

Retention

Revenue Recovery's member side as a connector runs it — the cancellation screen's question and offer in the core's words, the checkout a door hands over written to the ledger, a sequence step's arrival with its coupon, the Stop, and every refusal with a stable reason.

Subscriby\Connector\Core\Retention. The screen is the core's: the creator decides whether the question is asked and which offers the project makes, the core picks the one offer the member's payment method can honour and phrases every sentence in the member's language, and the dashboard reads every answer. A connector is one more place a member meets it. The contract takes the InstallationRef the conversation runs on and the IdentityRecord of the account that is talking, finds the project behind the one and the member behind the other, and answers in summaries whose every sentence the core already wrote. A bot never composes an offer from a kind and a figure; it prints what it was handed and reports what was tapped, and the portal and the bot ask and offer the same things in the same words. The same port carries Lead nurture's three member-side moments: a checkout your door hands over, a sequence step's button opening your bot, and the Stop every step carries.

cancellationScreenFor()

$screen = $this->retention->cancellationScreenFor($bot->installationRef(), $chat->identityRecord());

if ($screen === null) {
    return;                                   // no live membership to cancel: no screen
}

$screen->subscriptionId;                      // the membership the screens are about
$screen->projectName; $screen->planName;      // for the confirmation's words
$screen->asksReason;                          // false when the creator switched the question off
foreach ($screen->reasons as $reason) {
    $reason->code;                            // too_expensive
    $reason->label;                           // "Too expensive", in the member's language
}
$screen->offer?->kind;                        // RetentionOfferKind::Pause | Discount | ReturnCoupon, or null for no offer
$screen->offer?->headline;                    // "Take a month off instead?"
$screen->offer?->sentence;                    // what the offer does, in one sentence
$screen->offer?->acceptLabel;                 // the button's words
$screen->offer?->couponCode;                  // the code, on a return coupon
$screen->accessEndsOn;                        // when a cancellation would end access, formatted, or null

Null while the account holds no live membership to cancel. reasons is empty when the project switched the question off, and offer is null when the project makes no offer on the member's payment method or the creator's plan lacks the offers, so a connector draws the screens it is handed and no other: the reason when asksReason, the offer when there is one, then its own confirmation.

recordCancellationFeedback()

try {
    $record = $this->retention->recordCancellationFeedback($installation, $chat->identityRecord(), $code, $note);
} catch (RetentionRefused $refused) {
    $this->send($chat, $refused->getMessage());   // reason_unknown, invalid_note, ...
}

$record->id;                                  // park it for the offer step
$record->offer;                               // the offer to show next, derived again by the core, or null

Writes the row the dashboard's Cancellations face shows, tells the creator under the Revenue Recovery alert class, raises subscription.cancellation_feedback, and answers the offer to show next. $note is the sentence the member typed or null when they skipped it; a note over 500 characters is invalid_note, a code the screen did not list is reason_unknown.

takeOffer()

try {
    $outcome = $this->retention->takeOffer($installation, $chat->identityRecord(), $record?->id);
} catch (RetentionRefused $refused) {
    // cancellation_unknown, offer_unavailable, gateway_refused
}

$outcome->kind;                               // what they got
$outcome->keepsSubscription;                  // true for a pause or a discount, false for a return coupon
$outcome->sentence;                           // what happens next, in the member's language
$outcome->couponCode;                         // the code to restate, on a return coupon

The offer is derived again by the core, never taken from the connector, so a stale screen cannot claim an offer the creator has since withdrawn (offer_unavailable). A pause holds the charge at the gateway first and pauses access second; a discount is applied at the gateway; a return coupon is handed over on the screen and in a message, and the cancellation goes on, which is why keepsSubscription is what a connector branches on: a pause or a discount ends the conversation with the sentence and a way back, a return coupon goes on to the connector's own confirmation with the code restated. gateway_refused means the gateway would not hold the charge or carry the discount; relay the sentence and offer the confirmation. Pass null as the id when the project asked no question.

declineOffer()

$record = $this->retention->declineOffer($installation, $chat->identityRecord(), $record?->id);   // null when no offer was made

Notes that the member passed on the offer, so the offers shown are counted against the offers taken on the creator's figures. Call it when the member taps past the offer, before the confirmation.

recordCheckoutStart()

$written = $this->retention->recordCheckoutStart(
    $installation,
    $chat->identityRecord(),
    $planId,
    $method->providerKey,                     // the method row's PaymentProviderKey: a gateway's word, or your native provider
    $method->id,                              // or null for a rail with no row of its own
);

Call it the moment your door hands the member the way to pay: the gateway's page, the invoice, the native prompt. The core writes the checkout to the ledger the dashboard's Checkouts face and the REST and MCP reads page, raises payment.pending for the project as the portal's doors always have, and the hourly sweep counts the row as stalled once the project's checkout window has passed with no settled charge, which opens the stalled-checkout sequences; the next charge that settles closes it. False when the project or the member is unknown or the rail is not one the core keys, so a door never fails over the ledger. An access code redemption or a free trial start is not a checkout: record nothing for them.

arriveFromSequence()

$arrival = $this->retention->arriveFromSequence($installation, $chat->identityRecord(), $enrollmentId);

if ($arrival === null) {
    return $this->home($chat);                // not this member's passage: the home screen, nothing recorded
}

$arrival->planId;                             // the plan to open, or null for the home screen
$arrival->couponCode;                         // the step's coupon, already recorded for the member on that plan, or null

When a member is reached on a connector that hands out start links, every sequence step's button opens the project's bot with the start payload seq_<enrollment id>. Hand the id after seq_ here: the core checks the passage is the member's, records the step's coupon for them on the plan the way the portal's coupon box does, so your checkout applies it under the coupon's own rules and refuses it the same way once spent, and answers the plan to open. Open the plan when there is one (the payment picker shows the coupon applied), the home screen otherwise.

stopSequences()

$stopped = $this->retention->stopSequences($installation, $chat->identityRecord());

Every step carries the Stop command, which your connector renders as a button; answer it here. The core exits every open passage of the member in the project and keeps them out of every sequence until a charge settles for them or they switch the follow-ups back on in the portal's account settings. True when the member was found and stamped, false for an account the project does not know; say so in a word and offer the way back to the menu.

Refusals

Every method throws Subscriby\Connector\Exceptions\RetentionRefused. getMessage() is the core's sentence in the member's language, which is what you relay; reason is stable and yours to branch on: installation_unknown (the ref names no project), member_unknown, subscription_unknown (no live membership), reason_unknown, invalid_note, cancellation_unknown (the id names none of the member's rows), offer_unavailable and gateway_refused. The three Lead nurture methods throw installation_unknown alone and answer false or null for everything else, because a door and a button must never fail over a ledger.

What is not here

The cancellation itself stays the connector's own confirmation, run through the subscription port as it always was, so a free trial still cancels outright and the decoy-guarded confirmation keeps its code. The creator's switches are RetentionManagement's; the grace ladder, the stall sweep, the sequences' steps and the figures are the core's whole subsystem and never a connector's to write: a connector records a checkout's start, receives a step's arrival and answers the Stop, and the core decides what a stall is, when a step goes out and where its button leads.

Read it fresh

The screen and the offer are computed when you ask; park the record's id across two taps, never the screen. The creator may switch the question or an offer off between them, and the core answers offer_unavailable rather than honouring a screen that no longer stands.

How is this guide?

Last updated on

Version

On this page

Subscriby is a product
designed by you — for you.
No boardroom full of executives deciding what we ships next. Our roadmap always shaped by you with your feedback.

Share feedback or a request

For AI agents: llms.txt · llms-full.txt