Skip to content
AskVault Docs
Try Free →

Stripe integration use cases

Written by Joseph Russo, Principal Architect, Networks and Tech, AskVault · Reviewed by Allison Chan
Last updated: · 5 min read

Identity: what the skill checks, and what it does not

Billing data is sensitive: dates, amounts, plans. You should know exactly what stands between a visitor and a change to a Stripe account.

What subscription_manager checks: the visitor must be signed in with identity verification, and your server must sign the customer's email as the user_id. The skill acts only when the email in the request is that signed email. An email the visitor merely types, or a signed user_id that is not an email, is refused before Stripe is ever called, and the bot is told to offer a teammate instead.

It then looks up the Stripe customer for that email, and refuses to act if Stripe has no customer with it.

What it does not do: there's no email-code verification step for visitors who aren't signed in. The discount_negotiator skill has no identity check at all; it acts on the Stripe customer ID the bot supplies.

1. What subscription_manager is not. A status lookup tool

Common billing questions customers ask ("when does my subscription renew?", "what plan am I on?") aren't answered by a dedicated live-lookup tool today. subscription_manager looks up the visitor's Stripe subscription internally, but only as a step inside an upgrade, downgrade, or refund action: it doesn't expose subscription details (plan, renewal date, invoice amount) back to the model as a standalone answer. For a pure status question, route to escalate_to_human or your own indexed billing FAQ content until a dedicated lookup path exists.

2. Refunds: built, not yet issued

The refund action is in the skill, but no refund is sent to Stripe today. A refund the visitor has confirmed (see use case 3) still has to pass the written-policy check, and that check can't yet read the ceiling out of your refund policy; a refund with no readable ceiling is declined.

How the refund path is designed to work, so you can prepare your policy:

  1. The visitor asks for a refund, then confirms the card with a yes. The request needs the customer's email, the Stripe charge ID, and an amount.
  2. Daily cap check. Refunds in the last 24 hours plus this one must come to at or under a fixed ceiling of 10,000 (in the charge's currency units). This ceiling is set by AskVault and isn't adjustable from the dashboard.
  3. Written policy check. AskVault searches your knowledge base with a fixed phrase about refund policy (not the visitor's words) and uses the top passage only if it scores at least 0.92 similarity. That passage must state a ceiling in one of these forms: "up to $500", "max $500", "maximum of $500", or "$500 limit" (also ₹, Rs, £, €, ¥, and INR/USD/EUR/GBP/AUD/CAD). Write the number without a thousands separator: "up to $1,000" is read as a ceiling of 1, so write "up to $1000". Phrasing like "less than $500" isn't recognised, and a policy with no recognisable ceiling declines every refund.
  4. If both pass, the refund is issued through Stripe's Refunds API.
  5. If the policy check fails, the skill declines and reports that to the bot. If the daily cap would be exceeded, the bot gets a generic error with the details hidden, not a message naming the cap. Either way there's no automatic hand-off to a human.

Time windows such as "within 14 days of the charge" are not checked: only the amount ceiling is.

3. Plan changes: confirmed by the visitor

The upgrade and downgrade actions run from chat once the visitor confirms. The bot first shows a confirm card; AskVault records it and runs the change only when a later message from the visitor, within 10 minutes of the card, is a short yes for the same request in the same conversation. A confirmation the AI writes for itself doesn't count, and a changed request gets a new card. On a yes, AskVault asks Stripe to update the subscription; if Stripe rejects the change, the subscription stays as it was. If Stripe doesn't answer (an outage or a timeout), AskVault can't tell whether the change went through, so check the subscription in Stripe.

How the plan-change path works:

"I want to upgrade from Starter to Growth."

  1. The customer's email is looked up in Stripe to find their subscription.
  2. Customer (or your prompt/config) supplies the target Stripe Price ID: there's no live pull of your Stripe Products catalog into the conversation today, so the bot needs that price id available from context or configuration.
  3. Customer confirms. The bot shows a confirm card and the customer replies yes (see Policy bounds).
  4. Stripe Subscription updated via Stripe's subscription-update API, with Stripe's default proration behavior.
  5. Result reported back to the bot.

Note on downgrades. Every downgrade requires a written subscription or cancellation policy in your knowledge base. AskVault searches with a fixed phrase about cancellation and downgrade policy and needs a passage scoring at least 0.92 similarity; it doesn't compare the policy with the plan requested. No such passage, and the downgrade is declined. Upgrades have no policy check.

4. What this integration does not do (yet)

To set expectations correctly:

  • No billing actions for visitors who aren't signed in. See Identity above.
  • No completed refunds today. See use case 2 above.
  • No automated failed-payment outreach. AskVault's Stripe webhook receiver doesn't yet act on invoice.payment_failed: no automatic WhatsApp/email nudge is sent.
  • No invoice retrieval. There's no skill that lists a customer's past invoices or returns PDF links; the underlying single-invoice lookup method exists in code but isn't wired into any skill yet.
  • No live subscription-status Q&A. See use case 1 above: subscription_manager only exposes upgrade/downgrade/refund, not a plain status answer.
  • No audience-tag sync from Stripe events. Subscription and invoice webhook events are received, but nothing currently updates AskVault audience tags or CRM records from them.

If your use case depends on any of these, the custom_webhook skill is the way to bridge to your own Stripe-connected backend today.

Webhook events AskVault receives

On connect, AskVault automatically registers a webhook endpoint on your Stripe account (no manual setup in Stripe Dashboard) and subscribes to:

  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.paid
  • invoice.payment_failed
  • checkout.session.completed

When an event names your connected Stripe account, AskVault checks its signature against the endpoint's signing secret and logs it. An event that doesn't name an account is acknowledged and dropped without a signature check. See What this integration does not do (yet) for what happens (and doesn't) beyond that today.

Policy bounds

The subscription_manager skill has these checks:

  • Visitor confirmation (checked by AskVault). When the bot first calls a refund, upgrade, or downgrade, AskVault holds the call, shows the visitor a confirm card and records that it did. The action runs only if a later message from the visitor, within 10 minutes of the card, is a short yes for the same request in the same conversation, and a yes works once. AskVault ignores a "confirmed" marker the bot writes itself. A late yes, a changed request, or a yes in another conversation gets a fresh card, and if AskVault can't check, the action stays paused. (A refund still stops at the written-policy check: see use case 2.)

The next three are applied by AskVault's code, not by the model:

  • Daily refund cap. A fixed ceiling of 10,000 (in the charge's currency units) on refunds per workspace across a rolling 24 hours, checked before every refund. Not adjustable from the dashboard.
  • Written policy match. Every refund and every downgrade must match a written policy in your knowledge base; no match means no action. Upgrades aren't policy-checked.
  • Idempotency. Repeating an identical request within 24 hours returns the earlier result instead of executing twice.

There's no per-visitor refund limit and no bounds screen in the dashboard.

Sample customer journey

End-to-end, for a plan upgrade:

  1. A signed-in customer asks to upgrade. Your site signed their email as the user_id with identity verification.
  2. The skill checks the email is that signed email, then looks it up in Stripe and finds the subscription.
  3. The bot shows a confirm card for the target plan, and the customer answers with a short yes within 10 minutes.
  4. On Yes, the Stripe subscription is updated through Stripe's subscription-update API: see use case 3.

No human is involved. A customer who isn't signed in is refused at step 2: see Identity.

Plan availability

Stripe use cases require:

  • AskVault Business or Enterprise plan. Free, Starter, Growth don't include the subscription_manager skill. Business+
  • Stripe connected to the workspace, and the skill enabled.
  • Stripe account in good standing. Stripe restrictions (high-risk merchant, missing KYC) limit some operations.

Privacy: what AskVault stores

  • AskVault never receives card numbers. The skill doesn't read or return card details.
  • AskVault keeps a record of each billing-skill call: the request as the bot sent it (customer email, action, target price ID or refund amount and charge ID, and the bot's justification) and the result. When a call reaches Stripe, the record also holds the body Stripe returned.
  • For the connection itself, AskVault stores the encrypted OAuth token and the encrypted signing secret of the webhook endpoint it registered.

Common pitfalls

Every refund fails. Expected today: see use case 2.

A plan change shows the confirm card again after the visitor said yes. The yes came after the 10 minutes ran out, or the request changed after the card was shown. The bot asks again.

"Customer not found". Either no Stripe customer has the email given in the conversation (the customer may have used a different email with Stripe), or Stripe returned an error when AskVault looked the customer up. The skill reports both the same way, so check Stripe's status page before assuming the email is wrong.

Downgrade blocked. No written policy matches the requested downgrade. Add or adjust the policy so subscription_manager can match it; otherwise the downgrade is declined.

Webhook events not arriving. The endpoint AskVault auto-registered on your Stripe account was deleted or the connection needs to be re-authorized. Reconnect Stripe to re-register it: no manual Dashboard configuration should be needed.

FAQ

Can the bot process refunds for amounts above the policy cap?

No. AskVault's code, not the model, stops both. A refund over your written ceiling is declined. A refund that would take the workspace over the daily cap fails with a generic error that doesn't name the cap. There's no automatic hand-off to a human: enable escalate_to_human if you want the bot to be able to route those requests to your team. (Today every refund is declined: see use case 2.)

Does this work for Stripe customers in India (UPI, RuPay)?

If your Stripe account accepts those payment methods, the resulting subscriptions and charges are ordinary Stripe objects and work the same as any other: plan-change actions aren't restricted by payment method.

Can I require a confirmation step before any billing action?

There's no setting for it: before a refund, upgrade, or downgrade the skill shows the visitor a confirm card and runs the action only after the visitor's own yes. See Policy bounds.

What happens if Stripe API is down?

The skill doesn't retry on its own. What the bot sees depends on where the failure happens: if Stripe returns an error during the customer lookup, the bot is told the customer wasn't found; if Stripe errors while fetching the subscription for a plan change, the bot is told the subscription or target plan is missing; if Stripe can't be reached at all, the bot gets a generic error with the details hidden. A "provider error" is only reported when the lookups succeed and the change itself fails at Stripe.

Can I see all bot-driven billing actions in an audit log?

Not as a dedicated screen today: there's no Audit Log page in the dashboard.

Was this page helpful?