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 nullNull 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 nullWrites 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 couponThe 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 madeNotes 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 nullWhen 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
Referral Management
A project's Referral Program as a connector's creator surface runs it — the options a setup needs, the programme in the core's words with its figures, the save from a draft, the pause, the resume and the delete, affiliates listed and read with their balances and payout details, approved, suspended and enrolled from a member search, and payouts recorded against what is payable.
Retention Management
A project's Revenue Recovery settings as a connector's creator surface runs them — the grace window with its ladder in words, the question, the digest, the three offers with the coupons a creator may pick, the checkout window and the trial reminder, read whole and saved one field at a time.