Documentation

Agent Billy Docs

Everything you need to set up Agent Billy, connect Stripe, and give your team safe role-based billing access.

Quick Start

Up and running in 5 minutes

Agent Billy has three setup steps. Each one takes about a minute.

1

Create your account

Go to agentbilly.ai/signup, choose your plan, and enter your email and password. No credit card required for the 14-day trial.

2

Connect your Stripe account

Generate a Restricted API Key in Stripe (see Connect Stripe below). Paste it into the onboarding wizard. Billy stores it in Azure Key Vault — your team never sees it.

3

Invite your team

Enter your team members' email addresses and assign each a role. They'll receive a magic-link invite and be ready to work immediately.

💡 Your Billy dashboard is available at {your-org}.agentbilly.ai within ~30 seconds of completing setup.
Stripe

Connect your Stripe account

Billy uses a Restricted API Key — not your full secret key. Restricted keys give Billy only the permissions it needs, and nothing else.

Never paste your full secret key (sk_live_...). Only restricted keys (rk_live_...) are accepted.

How to create a Restricted Key

  1. 1Open the Stripe Dashboard → Developers → API Keys and click Create restricted key.
  2. 2Give it a name like Agent Billy.
  3. 3Under Permissions, enable the following:
  4. 4Copy the key — it starts with rk_live_. Paste it into the Billy onboarding wizard.
ResourcePermission
ChargesRead
CustomersRead + Write
SubscriptionsRead + Write
InvoicesRead + Write
RefundsWrite
Payment MethodsRead

How Billy stores your key

When you paste your key, it is immediately encrypted and stored in Azure Key Vault. The plaintext key is never written to a database, log file, or browser. Your team members and Billy's dashboard never receive the key — only Billy's server-side API calls use it.

Team

Invite your team

Invite team members from the onboarding wizard or later from Settings → Team in your dashboard.

  1. 1Go to Settings → Team → Invite Member.
  2. 2Enter the team member's work email address.
  3. 3Select their role (see Roles & Permissions below).
  4. 4Click Send Invite. They'll receive a magic-link email valid for 48 hours.
  5. 5Once they accept, they appear in your team list and can log into your Billy dashboard immediately.
💡 Team member limits depend on your plan: Starter = 3 members, Pro = 10, Business = unlimited.
Permissions

Roles & Permissions

Billy has four built-in roles. Each role is a strict subset of the one above it — there's no permission creep.

Owner

Full control. Manages team, views audit log, changes settings. Only one Owner per org.

Can do

  • All billing operations
  • Team management
  • Full audit log
  • Settings & integrations
  • Cancel subscription
Billing Manager

Day-to-day billing operations. $5,000 refund cap per transaction.

Can do

  • Issue refunds (≤ $5,000)
  • Manage subscriptions
  • Create & send invoices
  • Update customer details
  • Search & view everything

Cannot do

  • Team management
  • Audit log
  • Settings
Billing Clerk

Small refunds and customer lookups. $100 refund cap.

Can do

  • Issue refunds (≤ $100)
  • View customers, charges, subscriptions
  • Update customer email/address

Cannot do

  • Cancel subscriptions
  • Create invoices
  • Manage products
Read Only

View everything, change nothing. Perfect for support staff who need context.

Can do

  • View all billing data
  • Search customers
  • Export reports (Pro+)

Cannot do

  • Any write operation
AI Agent

Using Billy as an AI Agent

Billy is also an MCP server. Connect it to Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool to manage billing with plain English.

Setup with Claude Desktop

  1. 1Install Billy's CLI: run npx agent-billy in your terminal. It will open a browser to authenticate your account.
  2. 2Once authenticated, add this to your claude_desktop_config.json:
JSON
{
  "mcpServers": {
    "agent-billy": {
      "command": "npx",
      "args": ["agent-billy", "--mcp"]
    }
  }
}

Restart Claude Desktop. Billy will appear in the MCP tools list.

Example conversations

You

What's going on with failed payments this week?

B

You had 7 failed payments totaling $1,245: - 4 expired cards (want me to send update reminders?) - 2 insufficient funds - 1 fraud block (Stripe Radar) The 4 expired cards are repeat customers. Want me to draft payment update emails?

You

Refund order #5678

B

That's a $45.99 charge to Jane Smith. This is within your $100 refund limit. Shall I proceed?

You

Yes

B

Done! Refund of $45.99 issued. She'll see it in 5–10 business days. Want me to email her a confirmation?

You

Show me all customers with overdue invoices

B

Found 3 customers with overdue invoices totaling $2,840: 1. Acme Corp — $1,200 (14 days overdue) 2. Globex — $940 (7 days overdue) 3. Initech — $700 (3 days overdue) Want me to send payment reminder emails to all three?

💡 All AI agent actions go through the same permission engine as the dashboard. A Billing Clerk cannot issue a $5,000 refund via Billy, even through Claude.
Security

Security model

Stripe keys in Azure Key Vault

Your Stripe restricted API key is encrypted and stored in Azure Key Vault. It is never written to any database, log file, or browser. Billy's server-side API calls retrieve the key at runtime — your team never sees it.

Per-customer container isolation

Each paying customer gets their own isolated container running on Azure Container Apps. Your Stripe data never touches another customer's system — there is no shared database or shared process.

Append-only audit log

Every action performed through Billy — whether from the dashboard or the AI agent — is logged with who did it, what they did, when, and from where. The audit log is append-only and cannot be edited or deleted.

Short-lived JWTs

Authentication tokens expire every hour. Refresh tokens are stored in httpOnly cookies and are never accessible from JavaScript. This limits blast radius if a device is compromised.

Spending limits enforced server-side

Refund caps and role restrictions are enforced on the server, not the client. A user cannot bypass limits by making direct API calls — all requests go through Billy's permission middleware.

FAQ

Frequently asked questions

Do I need a specific Stripe plan?

No. Billy works with any Stripe account — including the free tier. You just need to be able to create API keys.

Can my team see my Stripe API keys?

Never. Keys are stored in Azure Key Vault and are never exposed to team members, the dashboard, or any browser.

Is Billy faster than Stripe's dashboard?

Yes. Billy syncs your Stripe data to a local database using the Stripe Sync Engine. Page loads and searches are database queries — not Stripe API calls. Most pages load in under 100ms.

What if I need more than 4 roles?

The Business plan includes a custom role builder. Most teams find the 4 built-in roles cover their needs.

Can I use Billy with Claude Desktop?

Yes. Run `npx agent-billy` to authenticate, then add Billy as an MCP server in your Claude Desktop config. See the AI Agent section above.

What happens if I cancel my subscription?

Your container is scaled to zero replicas immediately. We keep your data for 30 days in case you change your mind. After 30 days, everything is permanently deleted.

Is my data backed up?

Billy syncs from Stripe — your source of truth is always Stripe. The local sync database is backed up daily. If Billy goes away, your Stripe data is completely unaffected.

Can I use a test Stripe key?

Yes. Keys starting with rk_test_ work fully. This is a good way to explore Billy before connecting your live account.

Still have questions?

We reply within a few hours.

Email us