Support Proposals
How the support AI records a billing change a customer asked for, such as extending a trial, so that a staff member approves or rejects it in the admin panel.
On this page
Quick Reference#
// config/magic-starter.php
'features' => [
Features::support(),
Features::billing(),
Features::supportProposals(),
],
| Item | Value |
|---|---|
| Tool | propose_billing_change, registered by your code through SupportToolRegistry. |
| Actions | extend_trial, cancel_at_period_end and resume. |
| Expiry | support.proposals.expires_hours, 72 by default. |
| Trial cap | support.proposals.max_trial_extension_days, 14 by default. |
| Who asks | The account owner only. |
| Who decides | Staff the admin panel clears for billing. |
Introduction#
A customer who writes "please give me a few more days on my trial" wants a change to their subscription. The support AI must not make that change: a model that can charge, cancel or extend on a customer's word is a model an attacker can talk into it. Support proposals split the work in three:
- The AI records the request.
propose_billing_changewrites a row and changes nothing else. - A staff member approves or rejects it in the admin panel, after reading the customer's own words.
- The package executes it on approval, through the same billing contract the operator's panel actions use, with the staff member as the actor.
A proposal is a support tool that writes. Tools never execute: the one write it makes is a row for a person to read, and only that person's approval changes the subscription.
Feature: Features::supportProposals(). It needs Features::support() and the billing features as well, because the billing features supply the owner gate (see Who May Ask and Who May Decide). Listing support-proposals alone turns nothing on.
Enabling#
// config/magic-starter.php
'features' => [
Features::support(),
Features::billing(),
Features::supportProposals(),
],
Publish the migration, create_support_proposals_table.php, with the rest of the support migrations and run it:
php artisan magic-starter:install --features=support
php artisan migrate
The table is part of the support migration list, so a host that installed support earlier runs the same command again: a migration already published is skipped and only the new one is added. Proposals point at conversations, messages and users, so when you copy the file by hand, stamp it after theirs.
Two keys bound the feature, under support.proposals:
| Key | Default | Env | Meaning |
|---|---|---|---|
expires_hours |
72 |
MAGIC_STARTER_SUPPORT_PROPOSALS_EXPIRES_HOURS |
How long a request can be approved after it is recorded |
max_trial_extension_days |
14 |
MAGIC_STARTER_SUPPORT_PROPOSALS_MAX_TRIAL_DAYS |
The most days one request may move a trial end |
Registering the Tool#
The package ships the tool and never registers it: the tool registry is empty until your code fills it, and your SDK adapter decides what the model is offered. Register ProposeBillingChangeTool in a service provider's boot():
namespace App\Providers;
use AnilcanCakir\MagicStarter\Support\SupportAi\Tools\ProposeBillingChangeTool;
use AnilcanCakir\MagicStarter\Support\SupportAi\Tools\SupportToolRegistry;
use Illuminate\Support\ServiceProvider;
class SupportToolServiceProvider extends ServiceProvider
{
public function boot(): void
{
if (config('services.support.proposals')) {
app(SupportToolRegistry::class)->register(ProposeBillingChangeTool::class);
}
}
}
Put the registration behind a switch in your host that defaults to off, as above. A model that can ask for a billing change deserves a staged rollout: turn it on for one environment, read the first proposals in the panel, then widen it. With the switch off the model is never offered the tool, whatever the feature flag says.
The tool is named propose_billing_change and takes three arguments:
| Argument | Meaning |
|---|---|
action |
extend_trial, cancel_at_period_end or resume |
until |
A calendar day, YYYY-MM-DD, for extend_trial only |
reason |
Why the customer asked, in the model's words, at most 500 characters |
The account and the owner check come from the conversation, never from an argument. The model names what to ask for, not for whom.
The Three Actions#
| Action | Runs on approval | Recorded only when |
|---|---|---|
extend_trial |
AdministersBilling::extendTrial() |
The subscription is on a trial that is not cancelled, and until is a real day after the current trial end and at most max_trial_extension_days past it |
cancel_at_period_end |
AdministersBilling::cancel() |
The subscription is active and not already cancelled |
resume |
AdministersBilling::resume() |
The subscription is cancelled and still inside its period |
The tool checks these before it writes, with the predicates the operator's own actions apply, so staff are never shown a request that approval would refuse on sight. Every refusal is a sentence addressed to the model ("The subscription is not on a trial, so there is nothing to extend."), which it relays to the customer. A request is also refused for a visitor without an account, a conversation without a billing account, an account without a Stripe subscription, a malformed date, and one that is already waiting: a conversation holds at most one pending request per action.
Lifecycle#
| Status | Meaning |
|---|---|
draft |
Written during an AI turn, hidden from staff |
pending |
The turn that wrote it was stored; staff may decide until expires_at |
executing |
An approval claimed it and is calling billing; the outcome is not yet known |
approved |
The change ran, or staff confirmed by hand that it applied |
failed |
The change was refused, or the request no longer held at approval |
rejected |
A staff member declined it |
expired |
The deadline passed with no decision, found by an approval or a rejection |
A draft stays hidden because the customer has not read the answer that announces it. When RespondToSupportConversation stores the turn, it promotes that turn's drafts to pending and sends staff a SupportConversationNeedsStaff alert with the reason proposal. A turn that also hands the conversation to staff sends one alert only, the handoff one, because staff open that thread anyway and find the request on it. A turn that fails or is superseded never lands, so its draft stays hidden and never blocks a new request: a retried turn finds its own row by trigger message and action. While that row is still a draft, the retry's parameters and reason replace the earlier ones, so the latest call wins; once it is pending or later, staff may be reading it and it is left as it is. Either way the tool answers with what is stored, such as Recorded: extend the trial to 2026-10-27., so the AI never promises a day staff will not see. A new request for an action is refused while another one for it is pending before its deadline or executing.
Approval reads the world again under a row lock instead of trusting the snapshot taken at recording. It moves a proposal to failed, with the reason on the row, when:
- the conversation has no billing account any more (
no_billable), or the account is another one than the request named (billable_changed); - the customer who asked is no longer the account owner (
owner_changed); - an
extend_trialday no longer fits the trial as it stands (params_stale).
A proposal found past expires_at is set to expired and not run. A rejection of such a proposal does the same: it is set to expired and the customer is not told it was declined.
Who May Ask and Who May Decide#
The owner gate. Only the account owner asks. The tool resolves the billing account from the conversation, then asks Gate::forUser($opener)->allows('manageBilling', $billable), the gate the billing endpoints apply. That gate belongs to the billing features, which is why support-proposals needs them. A member of a team who is not its owner gets a sentence telling them to write in from the owner's account. Approval asks the gate again, so an owner who was replaced between the request and the decision fails the proposal.
The billing staff gate. Only a staff member the admin panel clears for billing decides. DecidesSupportProposals requires a FilamentUser that can access the panel it is given and passes BillingAuthorization::allows($staff, $panel) for that same panel, so the plugin rule of the panel the decision is made in applies even when no panel is current, as in a queued job or a test: an empty magic-starter.admin.billing_emails lets every panel admin through, a non-empty one admits only the addresses it lists, and an authorizeBillingUsing() callback on the plugin replaces both. The decision buttons are hidden from everyone else, and the contract re-checks on its own, so a crafted Livewire call is refused.
DecidesSupportProposals is bound only where Filament is installed.
Ordering Guarantee#
Stripe has no rollback. A charge or a trial change that already happened stays, whatever the database does afterwards. So approval is ordered to keep the database from lying about it:
- In one short transaction, under a row lock, it re-checks the request and claims the row as
executing. A second approval finds the row no longerpendingand stops. - With no database transaction open, it calls
AdministersBilling. The Stripe call and thebilling_eventsrows it writes commit on their own. - In a second short transaction it re-reads the row under its lock and, only while it is still
executing, writesapprovedand posts the customer's line. If another staff member marked it applied or failed while billing ran, that decision stands and no second line is posted.
Two outcomes follow:
- A
BillingAdministrationRefused(the subscription is no longer on a trial, Stripe rejected the call) leaves the rowfailedwith the refusal's reason. - A
rail_errorrefusal caused by a Stripe connection failure (Stripe\Exception\ApiConnectionException: a timeout, a dropped connection) is the exception: the request may have reached Stripe and applied, so the row staysexecuting, the customer is told nothing, and the refusal still reaches the panel. - Any other fault, such as a process killed mid-call, leaves the row
executing. That status means the outcome is unknown. Open the account's billing events and check whether the change applied: use Mark applied with a reason if it did, which setsapprovedand tells the customer, or Mark failed with a reason if it did not, which tells the customer nothing. Either one records you as the final decider. Never approve twice by other means: the claim exists so that a second approval cannot charge again, and neither mark calls billing.
What Staff See#
A "Billing requests" tab on the support conversation page, shown only while the feature is on. It lists every proposal that is not a draft: the action, its parameters, the status, the requester, and when it was created and expires. Below the lg breakpoint only the action and the status stay, and the status notes a request whose deadline passed; the rest is in the request's details.
The details of a request carry what a staff member needs to decide:
- the customer's own words, from the message that triggered it;
- the AI's rationale;
- for a trial extension, the current trial end and how many times the account's trial was already extended;
- how many customer messages arrived since the request, which may have changed or withdrawn it.
The customer's words and the rationale are untrusted text. They are shown as escaped plain text, never HTML or Markdown, and labelled unverified: the rationale is the model's reading of the customer, not a fact.
Each row's actions sit in one menu, so they are reached without scrolling the table sideways. The menu offers Details on every row, Approve and Reject (with a reason) on a pending request before its deadline, and Mark applied and Mark failed (each with a reason) on an executing one. Each decision is audited as support.proposal_approved, support.proposal_rejected, support.proposal_marked_applied or support.proposal_marked_failed.
What the Customer Sees#
The customer never sees a proposal row. The AI tells them in its answer that a person will review the request, and the thread then gets a system activity line in the conversation's language, not the staff member's:
| Outcome | Line |
|---|---|
| Approved, or marked applied | A teammate approved your request: Extend the trial. |
| Rejected | A teammate declined your request: Extend the trial. |
| Billing refused the change | We could not apply your request (Extend the trial). A teammate will follow up here. |
The thread refreshes through SupportConversationUpdated. A request that fails the re-check at approval, an expired request, an approval left executing and a Mark failed post no line, because nothing was decided that the customer can act on; staff follow up in the thread.
Gotchas#
| Mistake | Fix |
|---|---|
Listing support-proposals alone |
It needs support and the billing features as well; listed alone it turns nothing on. |
| Expecting the package to register the tool | It never does. Register ProposeBillingChangeTool yourself, behind a switch that defaults to off. |
Reading an executing row as in progress |
After a crash it means the outcome is unknown. Check the account's billing events, then use Mark applied or Mark failed with a reason. |
Calling DecidesSupportProposals::approve() inside a database transaction |
It refuses, because a rollback would hide a billing call that already happened. |
| Waiting for a customer's "cancel" to reach the model | The handoff classifier hands billing words to staff first, so such a message never reaches the model. |
| Letting a team member who is not the owner ask | Only the account owner may ask; others get a sentence pointing them to the owner. |
Related Documentation#
- Support AI Tools: the registry and the rules every tool follows.
- Support Desk: the conversations a proposal belongs to.
- Billing: the contract an approved proposal runs through.
- Admin Panel: the staff gate that decides.