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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Stripe billing and payments from Guild agents

> Connect Guild agents to Stripe to query charges, process refunds, manage subscriptions and invoices, and retrieve balance and payout data.

Integrations · Stripe

A Guild agent can query charges, process refunds, manage customers and subscriptions, and retrieve balance and payout data directly in Stripe. Guild stores the Stripe secret key server-side and injects it into every request, so agent code never handles the credential. Credential policies let you limit which operations each agent can call, and every request runs through Guild's audit trail.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Stripe.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Stripe to your first agent.

## What the Stripe integration exposes

The integration is published as `guildai~stripe-openapi` and covers customers, payment intents, charges, refunds, invoices, subscriptions, products, prices, payouts, balance, and Checkout Sessions. Tools follow the `stripe_openapi_` naming prefix. Read operations use GET tools; write operations use POST and DELETE tools to create, update, cancel, finalize, void, and delete Stripe objects.

## How it works

**1. Open credentials in Guild**

Go to **Access & setup > Credentials** in your Guild account or organization. Click **Connect**, then search for and select **stripe-openapi**.

**2. Paste your Stripe key**

Enter your Stripe secret key into the **API Key** field. Guild sends it as a bearer token in the `Authorization` header on every request.

**3. Import tools into your agent**

Import `StripeOpenapiTools` from `@guildai-services/guildai~stripe-openapi` and spread it into your agent's `tools` object. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only the tools your agent needs.

## Why Stripe access needs governing

Stripe credentials carry write access to billing objects: they can cancel subscriptions, process refunds, delete customers, and void invoices. Guild stores the secret key server-side and never exposes it to agent code. The credential proxy injects authentication only after all policy checks pass, so agents cannot bypass access rules.

With [credential policies](https://docs.guild.ai/platform/credential-policies.md), you write ALLOW and DENY rules that restrict which `stripe_openapi_` operations each agent or workspace may call. A rule that denies `stripe_openapi_delete_*` and `stripe_openapi_post_*` turns any agent into a read-only reporter. You can scope one credential to multiple agents with different rule sets. By contrast, an unscoped allow-all policy, which Guild creates by default, gives every agent the same access as the key itself.

## About the Stripe integration

Agents can read and manage core Stripe billing objects including customers, subscriptions, invoices, and products. They can process refunds, query payment intents and charges, and retrieve balance and payout information. Authentication uses a Stripe secret key. The integration is `guildai~stripe-openapi`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Stripe**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **stripe-openapi**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { StripeOpenapiTools } from "@guildai-services/guildai~stripe-openapi"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Stripe.",
  tools: { ...StripeOpenapiTools },
})
```

### Selecting specific tools

Tools are named with the `stripe_openapi_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~stripe-openapi`:

> [accordion] All 142 tools
>
> | Tool | What it does |
> | - | - |
> | `stripe_openapi_delete_customers_customer` | Permanently deletes a customer. |
> | `stripe_openapi_delete_customers_customer_bank_accounts_id` | Delete a specified source for a given customer. |
> | `stripe_openapi_delete_customers_customer_cards_id` | Delete a specified source for a given customer. |
> | `stripe_openapi_delete_customers_customer_discount` | Removes the currently applied discount on a customer. |
> | `stripe_openapi_delete_customers_customer_sources_id` | Delete a specified source for a given customer. |
> | `stripe_openapi_delete_customers_customer_subscriptions_subscription_exposed_id` | Cancels a customer’s subscription. |
> | `stripe_openapi_delete_customers_customer_subscriptions_subscription_exposed_id_discount` | Removes the currently applied discount on a customer. |
> | `stripe_openapi_delete_customers_customer_tax_ids_id` | Deletes an existing tax\_id object. |
> | `stripe_openapi_delete_invoices_invoice` | Permanently deletes a one-off invoice draft. |
> | `stripe_openapi_delete_products_id` | Delete a product. |
> | `stripe_openapi_delete_products_product_features_id` | Deletes the feature attachment to a product |
> | `stripe_openapi_delete_subscriptions_subscription_exposed_id` | Cancels a customer’s subscription immediately. |
> | `stripe_openapi_delete_subscriptions_subscription_exposed_id_discount` | Removes the currently applied discount on a subscription. |
> | `stripe_openapi_get_balance` | Retrieves the current account balance, based on the authentication that was used to make the request. |
> | `stripe_openapi_get_balance_history` | Returns a list of transactions that have contributed to the Stripe account balance (for example, charges, transfers, and so on). |
> | `stripe_openapi_get_balance_history_id` | Retrieves the balance transaction with the given ID. |
> | `stripe_openapi_get_charges` | Returns a list of charges you’ve previously created. |
> | `stripe_openapi_get_charges_charge` | Retrieves the details of a charge that has previously been created. |
> | `stripe_openapi_get_charges_charge_dispute` | Retrieve a dispute for a specified charge. |
> | `stripe_openapi_get_charges_charge_refunds` | You can see a list of the refunds belonging to a specific charge. |
> | `stripe_openapi_get_charges_charge_refunds_refund` | Retrieves the details of an existing refund. |
> | `stripe_openapi_get_charges_search` | Search for charges you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_checkout_sessions` | Returns a list of Checkout Sessions. |
> | `stripe_openapi_get_checkout_sessions_session` | Retrieves a Checkout Session object. |
> | `stripe_openapi_get_checkout_sessions_session_line_items` | When retrieving a Checkout Session, there is an includable line\_items property containing the first handful of those items. |
> | `stripe_openapi_get_customers` | Returns a list of your customers. |
> | `stripe_openapi_get_customers_customer` | Retrieves a Customer object. |
> | `stripe_openapi_get_customers_customer_balance_transactions` | Returns a list of transactions that updated the customer’s balances. |
> | `stripe_openapi_get_customers_customer_balance_transactions_transaction` | Retrieves a specific customer balance transaction that updated the customer’s balances. |
> | `stripe_openapi_get_customers_customer_bank_accounts` | You can see a list of the bank accounts belonging to a Customer. |
> | `stripe_openapi_get_customers_customer_bank_accounts_id` | By default, you can see the 10 most recent sources stored on a Customer directly on the object, but you can also retrieve details about a specific bank account stored on the Stripe account. |
> | `stripe_openapi_get_customers_customer_cards` | You can see a list of the cards belonging to a customer. |
> | `stripe_openapi_get_customers_customer_cards_id` | You can always see the 10 most recent cards directly on a customer; this method lets you retrieve details about a specific card stored on the customer. |
> | `stripe_openapi_get_customers_customer_cash_balance` | Retrieves a customer’s cash balance. |
> | `stripe_openapi_get_customers_customer_cash_balance_transactions` | Returns a list of transactions that modified the customer’s cash balance. |
> | `stripe_openapi_get_customers_customer_cash_balance_transactions_transaction` | Retrieves a specific cash balance transaction, which updated the customer’s cash balance. |
> | `stripe_openapi_get_customers_customer_discount` | get\_customers\_customer\_discount |
> | `stripe_openapi_get_customers_customer_payment_methods` | Returns a list of PaymentMethods for a given Customer |
> | `stripe_openapi_get_customers_customer_payment_methods_payment_method` | Retrieves a PaymentMethod object for a given Customer. |
> | `stripe_openapi_get_customers_customer_sources` | List sources for a specified customer. |
> | `stripe_openapi_get_customers_customer_sources_id` | Retrieve a specified source for a given customer. |
> | `stripe_openapi_get_customers_customer_subscriptions` | You can see a list of the customer’s active subscriptions. |
> | `stripe_openapi_get_customers_customer_subscriptions_subscription_exposed_id` | Retrieves the subscription with the given ID. |
> | `stripe_openapi_get_customers_customer_subscriptions_subscription_exposed_id_discount` | get\_customers\_customer\_subscriptions\_subscription\_exposed\_id\_discount |
> | `stripe_openapi_get_customers_customer_tax_ids` | Returns a list of tax IDs for a customer. |
> | `stripe_openapi_get_customers_customer_tax_ids_id` | Retrieves the tax\_id object with the given identifier. |
> | `stripe_openapi_get_customers_search` | Search for customers you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_invoices` | You can list all invoices, or list the invoices for a specific customer. |
> | `stripe_openapi_get_invoices_invoice` | Retrieves the invoice with the given ID. |
> | `stripe_openapi_get_invoices_invoice_lines` | When retrieving an invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. |
> | `stripe_openapi_get_invoices_search` | Search for invoices you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_payment_intents` | Returns a list of PaymentIntents. |
> | `stripe_openapi_get_payment_intents_intent` | Retrieves the details of a PaymentIntent that has previously been created. |
> | `stripe_openapi_get_payment_intents_intent_amount_details_line_items` | Lists all LineItems of a given PaymentIntent. |
> | `stripe_openapi_get_payment_intents_search` | Search for PaymentIntents you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_payment_methods` | Returns a list of all PaymentMethods. |
> | `stripe_openapi_get_payment_methods_payment_method` | Retrieves a PaymentMethod object attached to the StripeAccount. |
> | `stripe_openapi_get_payouts` | Returns a list of existing payouts sent to third-party bank accounts or payouts that Stripe sent to you. |
> | `stripe_openapi_get_payouts_payout` | Retrieves the details of an existing payout. |
> | `stripe_openapi_get_prices` | Returns a list of your active prices, excluding inline prices. |
> | `stripe_openapi_get_prices_price` | Retrieves the price with the given ID. |
> | `stripe_openapi_get_prices_search` | Search for prices you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_products` | Returns a list of your products. |
> | `stripe_openapi_get_products_id` | Retrieves the details of an existing product. |
> | `stripe_openapi_get_products_product_features` | Retrieve a list of features for a product |
> | `stripe_openapi_get_products_product_features_id` | Retrieves a product\_feature, which represents a feature attachment to a product |
> | `stripe_openapi_get_products_search` | Search for products you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_refunds` | Returns a list of all refunds you created. |
> | `stripe_openapi_get_refunds_refund` | Retrieves the details of an existing refund. |
> | `stripe_openapi_get_subscriptions` | By default, returns a list of subscriptions that have not been canceled. |
> | `stripe_openapi_get_subscriptions_search` | Search for subscriptions you’ve previously created using Stripe’s Search Query Language. |
> | `stripe_openapi_get_subscriptions_subscription_exposed_id` | Retrieves the subscription with the given ID. |
> | `stripe_openapi_post_charges` | This method is deprecated and will be removed soon. |
> | `stripe_openapi_post_charges_charge` | Updates the specified charge by setting the values of the parameters passed. |
> | `stripe_openapi_post_charges_charge_capture` | This method is deprecated and will be removed soon. |
> | `stripe_openapi_post_charges_charge_dispute` | post\_charges\_charge\_dispute |
> | `stripe_openapi_post_charges_charge_dispute_close` | post\_charges\_charge\_dispute\_close |
> | `stripe_openapi_post_charges_charge_refund` | When you create a new refund, you must specify either a Charge or a PaymentIntent object. |
> | `stripe_openapi_post_charges_charge_refunds` | When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it. |
> | `stripe_openapi_post_charges_charge_refunds_refund` | Update a specified refund. |
> | `stripe_openapi_post_checkout_sessions` | Creates a Checkout Session object. |
> | `stripe_openapi_post_checkout_sessions_session` | Updates a Checkout Session object. |
> | `stripe_openapi_post_checkout_sessions_session_expire` | A Checkout Session can be expired when it is in one of these statuses: open |
> | `stripe_openapi_post_customers` | Creates a new customer object. |
> | `stripe_openapi_post_customers_customer` | Updates the specified customer by setting the values of the parameters passed. |
> | `stripe_openapi_post_customers_customer_balance_transactions` | Creates an immutable transaction that updates the customer’s credit balance. |
> | `stripe_openapi_post_customers_customer_balance_transactions_transaction` | Most credit balance transaction fields are immutable, but you may update its description and metadata. |
> | `stripe_openapi_post_customers_customer_bank_accounts` | When you create a new credit card, you must specify a customer or recipient on which to create it. |
> | `stripe_openapi_post_customers_customer_bank_accounts_id` | Update a specified source for a given customer. |
> | `stripe_openapi_post_customers_customer_bank_accounts_id_verify` | Verify a specified bank account for a given customer. |
> | `stripe_openapi_post_customers_customer_cards` | When you create a new credit card, you must specify a customer or recipient on which to create it. |
> | `stripe_openapi_post_customers_customer_cards_id` | Update a specified source for a given customer. |
> | `stripe_openapi_post_customers_customer_cash_balance` | Changes the settings on a customer’s cash balance. |
> | `stripe_openapi_post_customers_customer_funding_instructions` | Retrieve funding instructions for a customer cash balance. |
> | `stripe_openapi_post_customers_customer_sources` | When you create a new credit card, you must specify a customer or recipient on which to create it. |
> | `stripe_openapi_post_customers_customer_sources_id` | Update a specified source for a given customer. |
> | `stripe_openapi_post_customers_customer_sources_id_verify` | Verify a specified bank account for a given customer. |
> | `stripe_openapi_post_customers_customer_subscriptions` | Creates a new subscription on an existing customer. |
> | `stripe_openapi_post_customers_customer_subscriptions_subscription_exposed_id` | Updates an existing subscription on a customer to match the specified parameters. |
> | `stripe_openapi_post_customers_customer_tax_ids` | Creates a new tax\_id object for a customer. |
> | `stripe_openapi_post_invoices` | This endpoint creates a draft invoice for a given customer. |
> | `stripe_openapi_post_invoices_create_preview` | At any time, you can preview the upcoming invoice for a subscription or subscription schedule. |
> | `stripe_openapi_post_invoices_invoice` | Draft invoices are fully editable. |
> | `stripe_openapi_post_invoices_invoice_add_lines` | Adds multiple line items to an invoice. |
> | `stripe_openapi_post_invoices_invoice_attach_payment` | Attaches a PaymentIntent or an Out of Band Payment to the invoice, adding it to the list of payments. |
> | `stripe_openapi_post_invoices_invoice_finalize` | Stripe automatically finalizes drafts before sending and attempting payment on invoices. |
> | `stripe_openapi_post_invoices_invoice_lines_line_item_id` | Updates an invoice’s line item. |
> | `stripe_openapi_post_invoices_invoice_mark_uncollectible` | Marking an invoice as uncollectible is useful for keeping track of bad debts that can be written off for accounting purposes. |
> | `stripe_openapi_post_invoices_invoice_pay` | Stripe automatically creates and then attempts to collect payment on invoices for customers on subscriptions according to your subscriptions settings. |
> | `stripe_openapi_post_invoices_invoice_remove_lines` | Removes multiple line items from an invoice. |
> | `stripe_openapi_post_invoices_invoice_send` | Stripe will automatically send invoices to customers according to your subscriptions settings. |
> | `stripe_openapi_post_invoices_invoice_update_lines` | Updates multiple line items on an invoice. |
> | `stripe_openapi_post_invoices_invoice_void` | Mark a finalized invoice as void. |
> | `stripe_openapi_post_payment_intents` | Creates a PaymentIntent object. |
> | `stripe_openapi_post_payment_intents_intent` | Updates properties on a PaymentIntent object without confirming. |
> | `stripe_openapi_post_payment_intents_intent_apply_customer_balance` | Manually reconcile the remaining amount for a customer\_balance PaymentIntent. |
> | `stripe_openapi_post_payment_intents_intent_cancel` | You can cancel a PaymentIntent object when it’s in one of these statuses: requires\_payment\_method, requires\_capture, requires\_confirmation, requires\_action or, in rare cases, processing. |
> | `stripe_openapi_post_payment_intents_intent_capture` | Capture the funds of an existing uncaptured PaymentIntent when its status is requires\_capture. |
> | `stripe_openapi_post_payment_intents_intent_confirm` | Confirm that your customer intends to pay with current or provided payment method. |
> | `stripe_openapi_post_payment_intents_intent_increment_authorization` | Perform an incremental authorization on an eligible. |
> | `stripe_openapi_post_payment_intents_intent_verify_microdeposits` | Verifies microdeposits on a PaymentIntent object. |
> | `stripe_openapi_post_payment_methods` | Creates a PaymentMethod object. |
> | `stripe_openapi_post_payment_methods_payment_method` | Updates a PaymentMethod object. |
> | `stripe_openapi_post_payment_methods_payment_method_attach` | Attaches a PaymentMethod object to a Customer. |
> | `stripe_openapi_post_payment_methods_payment_method_detach` | Detaches a PaymentMethod object from a Customer. |
> | `stripe_openapi_post_payouts` | To send funds to your own bank account, create a new payout object. |
> | `stripe_openapi_post_payouts_payout` | Updates the specified payout by setting the values of the parameters you pass. |
> | `stripe_openapi_post_payouts_payout_cancel` | You can cancel a previously created payout if its status is pending. |
> | `stripe_openapi_post_payouts_payout_reverse` | Reverses a payout by debiting the destination bank account. |
> | `stripe_openapi_post_prices` | Creates a new Price for an existing Product. |
> | `stripe_openapi_post_prices_price` | Updates the specified price by setting the values of the parameters passed. |
> | `stripe_openapi_post_products` | Creates a new product object. |
> | `stripe_openapi_post_products_id` | Updates the specific product by setting the values of the parameters passed. |
> | `stripe_openapi_post_products_product_features` | Creates a product\_feature, which represents a feature attachment to a product |
> | `stripe_openapi_post_refunds` | When you create a new refund, you must specify a Charge or a PaymentIntent object on which to create it. |
> | `stripe_openapi_post_refunds_refund` | Updates the refund that you specify by setting the values of the passed parameters. |
> | `stripe_openapi_post_refunds_refund_cancel` | Cancels a refund with a status of requires\_action. |
> | `stripe_openapi_post_subscriptions` | Creates a new subscription on an existing customer. |
> | `stripe_openapi_post_subscriptions_subscription_exposed_id` | Updates an existing subscription to match the specified parameters. |
> | `stripe_openapi_post_subscriptions_subscription_migrate` | Upgrade the billing\_mode of an existing subscription. |
> | `stripe_openapi_post_subscriptions_subscription_pause` | Pauses a subscription by transitioning it to the paused status. |
> | `stripe_openapi_post_subscriptions_subscription_resume` | Initiates resumption of a paused subscription, optionally resetting the billing cycle anchor and creating prorations. |

## Frequently asked questions

> [accordion] Can I limit an agent to read-only Stripe access?
>
> Yes. Write a credential policy that denies all `stripe_openapi_post_*` and `stripe_openapi_delete_*` operations. Guild's credential proxy blocks any matching request before it reaches Stripe, regardless of what the agent asks for. See [credential policies](https://docs.guild.ai/platform/credential-policies.md) for rule syntax.

> [accordion] Does Guild support Stripe webhook events?
>
> No. The catalog entry for `guildai~stripe-openapi` lists no webhook events, so the integration does not receive or process inbound Stripe webhooks.

> [accordion] Can different agents in the same workspace use different Stripe accounts?
>
> Yes. Connect a dedicated credential on each installed agent's detail page. Guild resolves credentials in order: grants and dedicated credentials take priority over workspace and account defaults, so each agent can authenticate with a different Stripe key.

> [accordion] Where does Guild store the Stripe secret key?
>
> Guild stores it server-side and injects it into outbound requests through its credential proxy. Agent code never sees the key. See [credentials](https://docs.guild.ai/platform/credentials.md) and [security architecture](https://docs.guild.ai/platform/security-architecture.md) for details.

## Put a governed agent on Stripe this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Stripe.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Stripe to your first agent.

## Related

**Also runs on Guild:** [Affinity](https://docs.guild.ai/integrations/affinity-openapi.md) · [Attio](https://docs.guild.ai/integrations/attio.md) · [Brex](https://docs.guild.ai/integrations/brex-openapi.md) · [Gong](https://docs.guild.ai/integrations/gong-openapi.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
