> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Actions: let customers manage subscriptions and billing in chat

> Let customers check their subscription, review invoices, change plans, and update billing details from the chat

Stripe Actions are Chatbase Actions that let your AI agent read and update a signed-in customer's Stripe billing data during a conversation: their subscription, invoices, plan, and billing details. They're built for subscription businesses that bill through Stripe, such as SaaS products and memberships, and they run in the chat bubble on your website.

Stripe Actions enable your AI agent to handle customer billing inquiries, subscription management, and account updates directly within the chat interface. These Actions provide secure, real-time access to customer payment information, streamlining support operations and improving the customer experience.

> [!NOTE]
>
> **Prerequisites:** Before using Stripe Actions, you must:
>
> 1. [Set up the Stripe integration](https://chatbase.co/docs/user-guides/integrations/stripe.md) with your Chatbase account
> 2. Configure [identity verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md) for secure customer authentication
> 3. Set up [contacts](https://chatbase.co/docs/user-guides/chatbot/contacts/contacts-overview.md) with valid `stripe_accounts` entries for each customer

## Available Stripe Actions

| Action | What it does |
| - | - |
| [Get subscription information](#1-get-subscription-information) | Show the customer's current plan, status, billing cycle, and pricing |
| [Get invoice history](#2-get-invoice-history) | Show the customer's invoices, payment details, and billing records |
| [Manage subscriptions](#3-manage-subscriptions) | Change plans, upgrade, downgrade, add payment methods, and cancel |
| [Change billing information](#4-change-billing-information) | Update the customer's billing address and other account details |

## How Stripe Actions work

Stripe Actions use Chatbase's identity verification system to securely access customer-specific data:

1. **User authentication**: Customers are identified using `window.chatbase("identify", {...})` with their unique user ID
2. **Contact matching**: The system matches the authenticated user ID to a contact record containing their Stripe account ID
3. **Secure data access**: Actions retrieve only the data associated with the authenticated customer's Stripe account
4. **Real-time responses**: The AI agent answers immediately using live Stripe data

> [!NOTE]
>
> Stripe Actions need an identified customer, so they don't run in **Action Preview** or **Compare**. To test them in the Playground, start the conversation with [Chat as user](https://chatbase.co/docs/user-guides/chatbot/playground.md#chat-as-user) and set the **User ID** to a customer whose contact record has a valid `stripe_accounts` entry. To test the real thing end to end, embed the [JavaScript script](https://chatbase.co/docs/developer-guides/website-integration/chat-bubble.md) on your site and run the Action there.

## Examples for subscription businesses

These examples show how the four Stripe Actions above can cover common billing conversations. Each one uses only the Actions on this page.

> [accordion] SaaS product: plan and payment questions
>
> A customer asks, "What plan am I on, and did last month's payment go through?" With **Get subscription information** and **Get invoice history** enabled, the AI agent shows the current plan, status, and renewal date, then lists recent invoices and their payment details. Both Actions only read data, so they're a low-risk place to start.

> [accordion] SaaS product: self-service upgrades
>
> A customer on your starter plan writes, "Upgrade my plan to the pro." With **Manage subscriptions** enabled and your plans defined in its settings, the AI agent can show the available plans and move the customer to the one they choose. Test upgrades and downgrades for correct proration before going live.

> [accordion] Membership: cancellations on your terms
>
> A member says, "I need to cancel my subscription." Configure the cancellation policy in **Manage subscriptions**, turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures), and call the Action from a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) that first checks what you need, such as the reason for leaving. The Procedure **Templates** tab includes ready-made flows for subscription cancellations and billing disputes that you can adapt.

> [accordion] Membership: billing detail updates
>
> A member who moved writes, "I need to update my billing address." With **Change billing information** enabled, the AI agent updates the address on their Stripe customer record, and the change is reflected in Stripe.

## How to create a Stripe Action

Every Stripe Action is created the same way. The [Action sections](#1-get-subscription-information) below list only what differs: which Action to pick and any extra configuration it needs.

**1. Navigate to Actions**

Go to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select your AI agent. Click **Build > Actions** in the left sidebar.

**2. Create the Action**

Click **Create Action**, then on the **Stripe** card select the Action named in its section below.

**3. Configure General Settings**

**Action Name:** A unique, descriptive name for the Action.

**When to use:** Detailed instructions for when the AI agent should use this Action.

To restrict the Action to [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) steps only, turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures). When it's on, the **When to use** field is hidden, because the AI agent no longer decides when to call the Action.

**4. Configure the Action's own settings**

[Manage subscriptions](#3-manage-subscriptions) adds a step for defining the available plans and cancellation policy. Every other Action skips straight to channels.

**5. Choose Channels**

Stripe Actions are compatible with the **Chat Bubble** channel only. Every other channel is incompatible and can't be selected. Use **Channels** to toggle the Action on or off for Chat Bubble. See [Channels](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#channels) for what configured, unconfigured, and incompatible mean.

**6. Enable and Test**

Ensure the Action is toggled to **Enabled**, then test it in the embedded widget on your site.

## Actions

### 1. Get subscription information

Retrieve and display customer subscription details, including current plan, status, billing cycle, and pricing information.

> [card] Best for:
>
> Answering questions about current subscription status, plan details, renewal dates, and subscription history.

**Common Use Cases:**

* "What's my current plan?"
* "When does my subscription renew?"
* "How much am I paying monthly?"
* "Is my subscription active?"

#### Settings

**Action:** **Stripe Get Subscription Info**.

![Selecting the get subscription Action from the Stripe options](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/stripe/stripe-action-get-subscription.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=7834982cd897a94754702e09bce3ad69)

> [!TIP]
>
> Test the Action in the embedded widget to ensure it correctly retrieves subscription data for authenticated customers.

![The AI agent returning subscription details in chat](https://mintcdn.com/chatbase/rsUPJArEUUJiVCBF/user-guides/chatbot/images/actions/stripe/get-subscriptions-action-result.png?fit=max\&auto=format\&n=rsUPJArEUUJiVCBF\&q=85\&s=272d24f4696d1718c661e01a8d4e8e96)

***

### 2. Get invoice history

Retrieve and display customer invoice history, payment details, and billing records.

> [card] Best for:
>
> Providing access to billing history, payment confirmations, invoice downloads, and payment troubleshooting.

**Common Use Cases:**

* "Show me my recent invoices"
* "Was my payment processed?"
* "Can you provide my billing history?"

#### Settings

**Action:** **Stripe Get Invoices**.

![Selecting the get invoices Action from the Stripe options](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/stripe/stripe-action-get-invoices.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=6d08760ee1f54b95d2b644166d536cf0)

> [!TIP]
>
> Test the Action with a sample customer request in the embedded widget.

![The AI agent returning invoice history in chat](https://mintcdn.com/chatbase/rsUPJArEUUJiVCBF/user-guides/chatbot/images/actions/stripe/get-invoices-action-result.png?fit=max\&auto=format\&n=rsUPJArEUUJiVCBF\&q=85\&s=1d3c131bb3a4284a35a7e762580727b4)

***

### 3. Manage subscriptions

Comprehensive subscription management, including plan changes, upgrades, downgrades, and cancellations.

> [card] Best for:
>
> Complete subscription lifecycle management: plan changes, adding payment methods, and cancellation handling.

**Common Use Cases:**

* "I want to upgrade my plan"
* "Upgrade my plan to the pro"
* "I need to cancel my subscription"
* "What plans are available?"

#### Settings

**Action:** **Stripe** → **Manage Subscriptions**.

![Configuring the subscription management Action](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/stripe/stripe-action-manage-subscription.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=c63f24a94f12cf38384dd5df28d6e1e3)

#### Define available plans and cancellations

Manage subscriptions has four sections: **General**, **Subscriptions**, **Cancellation**, and **Channels**. Plans and cancellations are set in the middle two.

> [tab] Subscriptions
>
> * **Customers can switch plans:** let customers move to another plan.
> * **Customers can change quantity of their plan:** let customers change how many units they pay for.
> * **Products:** pick the products customers can choose from, with **Minimum** and **Maximum** quantity rules.
> * **Prorate subscription updates:** charge or credit the difference when a plan changes. Choose **Invoice immediately** or **Issue invoice at the end of billing period**.
>
> ![The Subscriptions section of Manage subscriptions, with plan switching and product options](https://mintcdn.com/chatbase/St1vNiMgEx0Vl5Y7/user-guides/chatbot/images/actions/stripe/stripe-action-manage-subscription-plans-config.png?fit=max\&auto=format\&n=St1vNiMgEx0Vl5Y7\&q=85\&s=393e4e4778d755e89933f8ea816c6210)

> [tab] Cancellation
>
> * **Cancel subscriptions:** let customers cancel.
> * **Cancel settings:** choose **Cancel immediately**, with an optional **Prorate**, or **Cancel at period end**.
>
> ![The Cancellation section of Manage subscriptions, with the cancel settings](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/stripe/stripe-action-manage-subscription-cancel-config.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=490f5af4f29912cf23b207c6c4028582)

> [!TIP]
>
> Test every scenario before going live: upgrading from basic to premium with proper proration, downgrading with the right billing adjustments, and the complete cancellation flow. All subscription changes should be immediately reflected in both Stripe and the customer experience.

![The AI agent managing a subscription in chat](https://mintcdn.com/chatbase/rsUPJArEUUJiVCBF/user-guides/chatbot/images/actions/stripe/stripe-manage-subscription-result.gif?s=d516c4f147cee6dd0aecd33d21de1cc2)

> [!TIP]
>
> Manage subscriptions changes what a customer pays. Consider turning on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures) and putting your eligibility checks in a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) ahead of the step that calls it, so plan changes and cancellations happen at a point you control.

***

### 4. Change billing information

Allow customers to update their billing address and other account information.

> [card] Best for:
>
> Self-service billing updates, address changes, and other account information updates.

**Common Use Cases:**

* "I need to update my billing address"
* "Update my billing email address"
* "Update my billing phone number"

#### Settings

**Action:** **Stripe** → **Change customer information**.

![Selecting the change billing information Action](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/stripe/stripe-action-change-billing.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=08c8dc5a67074763706e9d70aad0522f)

> [!TIP]
>
> Test the Action with various scenarios to ensure only authenticated customers can make changes, and verify that billing updates are reflected in both Stripe and the customer's account.

![The AI agent updating billing information in chat](https://mintcdn.com/chatbase/rsUPJArEUUJiVCBF/user-guides/chatbot/images/actions/stripe/stripe-change-billing-result.png?fit=max\&auto=format\&n=rsUPJArEUUJiVCBF\&q=85\&s=0eefe8674b0c838a51aba5b7b461c566)

***

## Limitations

* **Stripe Actions require an authenticated customer.** Every Action reads or writes the signed-in customer's own Stripe record, so identity verification must be configured and the customer must be identified.
* **Each customer needs a contact record with a valid `stripe_accounts` entry.** Without it, the Action has no Stripe customer to act on.
* **In the Playground, they only run through Chat as user.** Start the conversation with [Chat as user](https://chatbase.co/docs/user-guides/chatbot/playground.md#chat-as-user) and a **User ID** that matches a contact with a valid `stripe_accounts` entry. **Action Preview** and **Compare** can't identify a customer, so the Actions don't run there.

## Troubleshooting

> [accordion] The AI agent never uses a Stripe Action
>
> **Possible causes:**
>
> * The Action is disabled in the dashboard, or turned off for the channel
> * The customer is not properly authenticated
> * The contact record is missing or has an invalid `stripe_accounts` entry
> * The **When to use** description is too vague to match what the customer asked
>
> **Solutions:**
>
> * Enable the Action and check its **Channels** step
> * Check your identity verification implementation
> * Validate that the contact record has a correct `stripe_accounts` entry
> * Rewrite **When to use** with the phrases customers actually type

> [accordion] No data is returned
>
> **Possible causes:**
>
> * Invalid Stripe customer ID in the contact record
> * The Stripe account has no subscription or invoice data
> * Stripe API permissions are insufficient
> * Network connectivity issues
>
> **Solutions:**
>
> * Verify the Stripe customer ID exists and is active
> * Check that the Stripe account has relevant data
> * Review the Stripe integration permissions
> * Test Stripe API connectivity directly

> [accordion] Authentication errors
>
> **Possible causes:**
>
> * User hash validation is failing
> * `external_id` doesn't match `user_id`
> * The contact record is not found
> * Identity verification was never called
>
> **Solutions:**
>
> * Verify hash generation matches the expected format
> * Ensure `external_id` exactly matches the authenticated `user_id`
> * Create a contact record for the customer
> * Implement the identity verification flow properly

## Best Practices

> [card] Security First
>
> Always validate customer identity before processing any billing-related request. Never allow unauthenticated access to financial data.

> [card] Testing Coverage
>
> Test all Actions with various scenarios, edge cases, and error conditions before going live: in the Playground through **Chat as user**, then from your real site with the embed in place.

> [card] Keep High-Stakes Actions on Rails
>
> Put plan changes and cancellations behind a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) with eligibility checks, so the AI agent doesn't decide on its own when a customer qualifies.

> [card] Clear Action Triggers
>
> Write specific **When to use** descriptions so the AI agent distinguishes a question about a plan from a request to change it.

## Frequently asked questions

> [accordion] Do Stripe Actions work on WhatsApp, email, or other channels?
>
> No. Stripe Actions are compatible with the **Chat Bubble** channel only. Every other channel is incompatible and can't be selected.

> [accordion] How do I stop the AI agent from changing a plan on its own?
>
> Turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures) for **Manage subscriptions**, then call it from a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) step after your eligibility checks. The AI agent then can't decide on its own to run it.

> [accordion] What happens when a Stripe Action fails?
>
> A Stripe Action that's set up correctly shouldn't fail in normal use. If one does, the AI agent tells the customer it can't complete the request. Check the [Troubleshooting](#troubleshooting) causes above, such as a missing `stripe_accounts` entry or insufficient Stripe permissions.

> [accordion] Can I test Stripe Actions with Tests?
>
> Yes. In [Tests](https://chatbase.co/docs/user-guides/chatbot/tests.md), Get subscription information and Get invoice history can run live against your connected Stripe account, because they only read data. Actions that change data, such as Manage subscriptions, can't run live: they return a generic success, or the mock response you write. Tests run against your published AI agent, while the Playground uses your draft.

> [accordion] How many Stripe Actions can I add, and what do they cost?
>
> Connecting Stripe needs the Basic plan or higher. Stripe Actions count toward your plan's Action limit: up to 8 Actions on Basic, 12 on Business, and a customizable limit on Enterprise. A reply that triggers an Action costs twice the model's usual message credits. See [Credit usage](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#credit-usage).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.