Stripe action presets

Five Stripe actions ship as ready-to-use presets in the Action Template Picker. Each is wired to your organization’s Stripe billing — the chatbot can answer subscription and invoice questions or, with confirmation, modify subscriptions on behalf of the user.

In this guide:

• The five presets
• How to enable a preset
• Destructive actions (cancel, update)
• The new single-invoice route
• Limitations

The five presets

Step 1: Enable a preset

On your chatbot detail page → Actions → New action → Template Picker → Stripe section.

Click the preset you want. The Action Builder opens, pre-filled with the preset’s:

• Endpoint (already pointing at your org’s billing routes).
• HTTP method.
• Input JSON schema.
• Default LLM prompt explaining when to call.
• destructive flag (true for cancel and update).

The slug field is locked — you can’t change it because the preset is wired to a specific endpoint contract.

Screenshot: The Stripe section of the Template Picker with all five presets.

Step 2: Save

Save the action. It’s now live and the bot will consider it on every message.

Step 3: Test

In the Playground:

• “What plan am I on?” → bot triggers get-subscription-status → returns “Growth (active).”
• “Show me my invoices.” → bot triggers list-invoices → renders a list inline.
• “Cancel my subscription.” → bot triggers cancel-subscription → shows confirmation card with the subscription ID, plan, and effective date.

Destructive actions: cancel and update

Both cancel-subscription and update-subscription are destructive — they modify your tenant’s billing in Stripe. The framework requires user confirmation by default:

1. Bot proposes the action with extracted parameters.
2. Confirmation card appears in chat: action name, parameters, expected effect, Confirm / Cancel buttons.
3. User confirms → action fires.
4. Stripe API responds → bot continues conversation.

For sensitive cancellations, escalate confirmation to a human teammate via Slack — see Confirmation flows.

The new single-invoice route

This PR also adds a backend proxy route specifically for fetching one invoice:

• GET /api/organizations/[id]/invoices/[invoiceId]
• Validates invoiceId against ^in_[A-Za-z0-9_]+$ to prevent SSRF.
• Forwards to Hilal’s backend with the user’s auth.
• Returns 400 for malformed IDs, 5xx for backend errors.

The stripe/get-invoice preset uses this route.

What runs on the backend vs. the frontend

To preserve security, no Stripe SDK is loaded in your browser. The chatbot:

1. Sees a Stripe action match.
2. Calls a Hilal Chatbot proxy route.
3. The proxy uses your saved Stripe credentials on the backend.
4. The Stripe SDK call happens server-side.
5. The response flows back through the proxy.

This means you don’t need to expose Stripe API keys to the frontend.

Limitations

• Tenant-scoped only. These presets manage your organization’s Stripe subscription with Hilal Chatbot — they don’t manage your customers’ Stripe records. For that, build a custom Stripe action keyed by customer ID.
• No webhook listening. These are on-demand reads; no real-time push of Stripe events into chat.
• No partial cancellations beyond what Stripe natively supports (immediate vs. period-end).

Permissions

• actions.create — to enable presets.
• actions.execute — for the bot to fire them.
• For destructive presets, also need admin role to bypass confirmation; otherwise the confirmation flow gates execution.

Troubleshooting

• Preset shows but call returns 404. The Hilal Chatbot backend may not yet expose the matching route. Confirm with support.
• Confirmation card appears but Confirm doesn’t fire. Check action audit log for the actual error.
• Cancel succeeds but Stripe still charges. Stripe cancellations are usually period-end by default — verify the cancel mode in the action parameters.

What’s next