Stripe AI agents: refund status, invoices and billing questions

What you can build

How to connect Stripe

1. 01Create a restricted Stripe key with read access to customers, invoices and refunds. Store it on the tool's auth settings as a bearer token.
2. 02Declare the customer id as a custom claim in the app's auth context so it enters the prompt for signed-in users, and require verified identity for the app.
3. 03Create read-only HTTP API tools, for example GET /v1/invoices?customer={{customer_id}} and GET /v1/refunds?customer={{customer_id}}, with safe_read.
4. 04If a refund tool exists at all, give it the destructive safety level and requires approval, and keep its description explicit about confirmation.
5. 05Attach the tools, sign in as a test user in the widget demo, and check the customer id in the rendered request.

Example tool definition

The shape a tool takes in the AgentRow builder API. Credentials are stored on the tool's auth settings, not in its configuration, so they never reach a prompt. Placeholders in double braces are filled by the model from the input schema.

{
  "name": "stripe_list_refunds",
  "type": "http_api",
  "description": "List recent refunds for the signed-in customer. Use when the user asks about a refund's status.",
  "auth_type": "bearer_token",
  "safety_level": "safe_read",
  "is_readonly": true,
  "config": {
    "method": "GET",
    "url": "https://api.stripe.com/v1/refunds",
    "query_params": { "customer": "{{customer_id}}", "limit": "5" },
    "allowed_domains": ["api.stripe.com"]
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string", "description": "The Stripe customer id from the user's identity claims" }
    },
    "required": ["customer_id"]
  }
}

What the run trace shows

Every call appears in the run trace with the rendered request, the response status and body, timing, retries and errors, plus what the model was shown of the result. If the model never called the tool, the toolbox step shows whether it was bound for that model call and why.