# Recurly MCP

> Recurly MCP Server automates subscription billing and account management by connecting your AI agent directly to Recurly's API. This server gives your client granular control over billing accounts, invoice history, product plans, and active subscriptions—all via natural conversation. Manage revenue data, check payment statuses, or onboard new customers without leaving your chat window.

## Overview
- **Category:** money-moves
- **Price:** Free
- **Tags:** subscriptions, billing, recurring-revenue, saas-billing, revenue-management, recurly

## Description

You connect your **Recurly** account to any AI client and get direct control over billing and subscriptions. This server lets your agent handle complex financial operations using only natural conversation. You don't have to jump through web forms or manually check dashboards; you just ask for what you need, and it pulls the data right into your chat window.

**Managing Billing Accounts:**
You can start by seeing every billing account you manage across the system using `list_billing_accounts`. If you know a specific ID, `get_account_details` lets you pull up the current balance, status, and all the associated metadata for that one account. You'll also need to onboard new clients; your agent registers brand-new billing accounts directly via the `create_billing_account` tool, requiring only the necessary user information.

**Tracking Payments and Invoices:**
Checking payment history is simple. Use `list_billing_invoices` to get a full list of invoices, letting you filter and track payments across specific date ranges. To dig into one transaction, `get_invoice` fetches all the detailed info for a single invoice using its unique ID. You can also pull a general list of recent financial activity with `list_transactions`, which gives you the IDs, dates, and dollar amounts for every major movement.

**Handling Subscriptions:**
For subscription status, your agent pulls everything together. `list_subscriptions` shows you all active *and* expired subscriptions linked to your account. When you know a specific ID, `get_subscription_details` gives you comprehensive info on that single item, including its current plan and detailed status information. You'll also need to see what pricing options are available; `list_subscription_plans` queries the entire catalog of subscription plans and their associated price points in the system.

**Pricing and Coupons:**
You can check out every active coupon code by calling `list_coupons`. This helps you confirm exactly which codes your customers can use on subscriptions or billing. You've got granular control over checking current account status, seeing historical invoice data, listing all plans available for sale, and even registering new users without ever leaving the chat window.

**Revenue Reporting:**
When it comes to money, you don't have to guess. Use `get_revenue_summary` to calculate and pull the necessary data points used when exporting overall revenue totals. Everything needed to reconcile your books lives here. This server lets you manage customer accounts, monitor payment statuses, track every plan, and handle all that complicated billing stuff—all through plain language prompts.

## Tools

### create_billing_account
Registers a new billing account within Recurly using required user information.

### get_account_details
Retrieves the current balance, status, and metadata for a specific billing account ID.

### get_invoice
Fetches detailed information about one specific invoice by its unique ID.

### get_revenue_summary
Calculates and retrieves data used for determining overall revenue export dates and summary metrics.

### get_subscription_details
Retrieves comprehensive details, including plan information and status, for a single subscription ID.

### list_billing_accounts
Generates an array of all currently managed billing account IDs within your Recurly system.

### list_billing_invoices
Provides a list of invoices, allowing you to filter and track payments over specific date ranges.

### list_coupons
Retrieves a list of all active coupon codes available for use on subscriptions or billing.

### list_subscription_plans
Queries and lists every available subscription plan and its associated price points in the system.

### list_subscriptions
Lists all active and expired subscriptions currently linked to your Recurly account.

### list_transactions
Gathers a list of recent financial transactions, providing transaction IDs, dates, and amounts.

## Prompt Examples

**Prompt:** 
```
List all active subscriptions in Recurly.
```

**Response:** 
```
I've retrieved your subscriptions. You have 10 active subscriptions, including 'Premium Plan' and 'Standard Tier'.
```

**Prompt:** 
```
Show me the subscription revenue breakdown by plan for the current billing period.
```

**Response:** 
```
Revenue by plan this billing period. "Enterprise Annual" leads with $234,000 (42% of total, 78 subscribers). "Professional Monthly" at $156,000 (28%, 520 subscribers). "Starter Monthly" at $89,000 (16%, 1,780 subscribers). "Team Annual" at $67,000 (12%, 134 subscribers). "Free Trial" has 234 active trials, 34% conversion rate. Total MRR: $546,000. Growth vs last period: +8.2%. 12 enterprise accounts renewed this month with an average 15% uplift.
```

**Prompt:** 
```
List all failed invoice payments from the last 14 days that need follow-up.
```

**Response:** 
```
34 failed payments in the last 14 days totaling $18,200. By reason: Card declined (18), Insufficient funds (9), Expired card (5), Network error (2). Retry status: 12 recovered after automatic retry (35% recovery). 22 still outstanding. High-value failures: Acme Corp $2,400 (card expired), TechVentures $1,800 (declined). 8 accounts are past the 3rd retry attempt and need manual outreach. Dunning emails sent: 67 total, 23% updated their payment method.
```

## Capabilities

### Manage Subscriptions
List all active or expired subscriptions, retrieving specific metadata and plan details.

### Query Billing Accounts
Retrieve detailed status information, balances, and metadata for any specified billing account ID.

### Check Invoice Status
Get payment history and current status details for specific invoice IDs.

### List Available Plans
Query the full catalog of available subscription plans and their associated pricing structures.

### Onboard New Customers
Register new customer billing accounts directly through an agent prompt, bypassing manual web form entry.

### Track Revenue Summary
Retrieve financial data and export dates used for calculating overall revenue totals.

## Use Cases

### Auditing a Revenue Gap
The billing manager notices a discrepancy between expected MRR and actual figures. They ask their agent to run `list_transactions` and cross-reference it with the summary data from `get_revenue_summary`. The agent identifies that 12 enterprise accounts renewed, but the total revenue figure was miscalculated because they only checked one tool.

### Handling a Support Inquiry
A customer asks, 'What's my current plan and balance?' Instead of directing them to a help center article, the agent calls `get_account_details` and `get_subscription_details`. The conversation flow is uninterrupted; they get the definitive answer immediately.

### Investigating Failed Payments
The finance team needs to know why $18,000 was lost last month. They prompt the agent to use `list_billing_invoices` for that period. The agent returns a breakdown showing 9 payments failed due to 'Insufficient funds,' allowing the team to target specific outreach.

### Setting up New Products
A product manager is validating new pricing structures. They first run `list_subscription_plans` to see existing options, then use `list_coupons` to check for promotional codes that might interfere with the new plan rollout.

## Benefits

- You get real-time visibility into payment failures. Instead of manually sifting through the dashboard, using `list_billing_invoices` allows your agent to tell you exactly which payments failed (e.g., 'Card declined') and how many need follow-up.
- Never guess a plan's cost again. Running `list_subscription_plans` gives you instant access to all pricing tiers, letting your client confirm the exact price for any given product during conversation.
- Account status checks are immediate. Need to know if a customer is active or suspended? Calling `get_account_details` provides the balance and current status instantly, without leaving the chat window.
- Audit billing history effortlessly. Instead of downloading massive CSV files, you can use `list_transactions` to pull specific data points—like total revenue for last Tuesday—and get a clean summary back.
- Onboarding new clients is faster. You don't need to copy-paste forms; using `create_billing_account` lets your agent register the customer account programmatically based on conversational input.

## How It Works

The bottom line is, your AI client runs complex billing API calls through simple conversation prompts.

1. Subscribe to the Recurly MCP Server and input your API v3 Key into the server settings.
2. Your AI agent calls the appropriate tool (e.g., `list_billing_invoices`) with required parameters (like an invoice ID).
3. The server executes the call against your live Recurly data and returns a structured JSON object that your agent interprets and presents to you.

## Frequently Asked Questions

**How do I check a customer's current balance using Recurly MCP Server?**
Call `get_account_details`. This tool fetches the precise current balance and status for any specific billing account ID. It tells you exactly what they owe right now.

**What is the difference between listing subscriptions and listing plans using Recurly MCP Server?**
`list_subscriptions` shows what your customers currently have active or expired. `list_subscription_plans` shows every pricing plan you offer to sell.

**Can I list all my invoices for a specific time range with Recurly MCP Server?**
Yes, use `list_billing_invoices`. You can pass date parameters to filter the results and get a clean list of every invoice that falls within your specified window.

**How do I register a new account using the create_billing_account tool?**
The `create_billing_account` tool requires structured input, typically including contact details and billing information. The agent handles mapping these inputs to successfully provision the account in Recurly.

**What specific data points does the `list_coupons` tool provide about active promotions?**
The tool lists all currently active coupons, including their unique coupon ID, expiration date, and discount value. This helps your agent quickly check promotion validity or understand a customer's potential savings before an enrollment.

**How do I use the `list_transactions` tool to analyze recent billing activity?**
It retrieves a chronological history of all recent financial movements associated with the account. You can pull specific transaction IDs, amounts, and dates to build detailed reports or audit past payments outside your AI client.

**What information does the `get_revenue_summary` tool provide regarding billing cycles?**
This function fetches necessary export data and summary metrics for accurate revenue reporting. It allows your agent to calculate key figures like Monthly Recurring Revenue (MRR) across specific, defined time periods.

**If I need to verify a client's current billing status, how do I use `get_account_details`?**
Just pass the specific account ID to get detailed information. The response includes the current balance, payment status, and associated metadata for quick verification. This is key when troubleshooting an invoice issue.

**Can I list all my active subscriptions using my AI agent?**
Yes! Use the `list_subscriptions` tool to retrieve a comprehensive list of all subscriptions registered in your Recurly account.