# Paddle MCP > Paddle MCP Server manages all billing operations for your SaaS platform. It lets your agent read customer profiles, list active and past-due subscriptions, fetch detailed transaction ledgers, and even pause or cancel recurring plans—all without you ever touching the Paddle dashboard. This tool handles everything from catalog pricing to complex tax calculations. ## Overview - **Category:** money-moves - **Price:** Free - **Tags:** billing, subscription-management, tax-compliance, payment-processing, revenue-analytics, invoice-management ## Description **Paddle MCP Server - Billing Management** This server gives your agent direct access to all of Paddle's billing data, letting you run complex financial queries or manage service plans without ever logging into the main dashboard. You don't need to touch the UI; you just tell your AI client what you need done. It handles everything from checking tax boundaries on a single customer account to listing every product price in the entire catalog. ### Customer and Account Records You can start by getting a full roster of who’s paying you with `list_customers`, which pulls an array of every current customer ID managed within Paddle. Once you have that list, you run `get_customer_details` against any specific ID to pull all the core data points for that client—this includes their billing status and crucial tax identification boundaries. Knowing these details lets your agent verify if a customer is set up correctly before running any changes. ### Subscriptions and Plans The subscription tools let you manage the entire service lifecycle. If you want an overview, `list_subscriptions` pulls basic status information and IDs for every plan active in your system. To drill down on one specific client's plan, use `get_subscription_details`. This tells you if the plan is currently active, suspended, or expired, plus its next scheduled billing date. When it comes time to adjust a plan, you have three options: **pausing** an account. Running `pause_subscription` temporarily suspends the client's ability to be billed without deleting their whole account record. If you need to cancel, `cancel_subscription` marks the service for termination; remember that this tool lets you specify whether the change needs to take effect immediately or if it should wait until the end of their current paid billing cycle. ### Transaction Auditing and History The financial tools let you audit every single dollar coming in. You can get a high-level overview using `list_transactions`, which provides a paginated list of all billing transactions, making it easy to filter for payments within a specific date range or check recent activity. For the deep dive—the kind that tracks down where a tax charge came from—you use `get_transaction_details`. This pulls every single piece of data associated with one payment record, including detailed breakdowns of any proration charges or localized taxes applied. ### Product and Pricing Catalog To manage what you're selling, your agent uses the catalog tools. You can get a complete inventory list using `list_catalog_products`, which returns the names, IDs, and general details for every single product defined in your Paddle setup. Separately, if you need to know how much those products cost right now, run `list_catalog_prices`. This pulls a full definition of all pricing structures, including the localized checkout prices that apply across different regions. By combining these tools—listing customer IDs with `list_customers`, pulling their core data with `get_customer_details`, checking their plan status with `get_subscription_details`, and then running an audit on a specific payment using `get_transaction_details`—your agent manages your entire billing backend. You'll handle everything from catalog pricing to complex tax calculations, keeping you out of the Paddle dashboard entirely. ## Tools ### cancel_subscription Cancels an active subscription, letting you specify if the effect is immediate or at the end of the current billing period. ### get_customer_details Fetches all core data points for a specific customer ID within Paddle's system. ### get_subscription_details Retrieves the current status and billing schedule for an individual subscription using its unique ID. ### get_transaction_details Pulls every specific detail associated with a single payment transaction, including tax breakdowns. ### list_catalog_prices Returns a complete list of all defined pricing structures and their localized checkout prices for your products. ### list_catalog_products Retrieves the names, IDs, and general details for every product listed in your Paddle catalog. ### list_customers Generates a list of all customer account IDs currently managed by Paddle. ### list_subscriptions Pulls an array of IDs and basic status information for every subscription active in your system. ### list_transactions Provides a paginated list of all billing transactions, useful for auditing recent payments or filtering by date range. ### pause_subscription Temporarily suspends an active subscription's billing status without deleting the customer account. ## Prompt Examples **Prompt:** ``` Find the subscription details for sub_01h9z2... ``` **Response:** ``` Subscription sub_01h9z2... is currently Active. Next billing date is set for Nov 14th, 2026. Billed at $49/month (Pro SaaS Tier). It is tied to customer ctm_01jh1. Want me to pause it? ``` **Prompt:** ``` List our most recent revenue transactions on Paddle. ``` **Response:** ``` I extracted the latest transactions from Paddle Billing. 1. txn_1w2... (Paid: $19.00 USD). 2. txn_4x9... (Prorated: $10.50 USD). 3. txn_9z2... (Paid: $99.00 USD). Want me to pull specific tax boundaries applied on the $99 payment? ``` **Prompt:** ``` Cancel subscription sub_active123 at the end of the billing cycle. ``` **Response:** ``` Action complete. Subscription sub_active123 has been marked for cancellation effective mapping `next_billing_period`. The user will not be charged again by the MoR, but remains active until the pre-paid term expires. ``` ## Capabilities ### Cancel a subscription Marks an active service plan for cancellation; you specify if the change takes effect immediately or when the current paid period ends. ### Get customer records Retrieves all key details, including tax boundaries and billing status, for a specific Paddle account ID. ### Check subscription status Gets the current state of a service plan—whether it's active, suspended, or expired—along with its next billing date. ### Pull transaction history Retrieves full details for any single payment record, allowing you to check tax amounts and proration charges. ### List all products and prices Gets a complete list of your SaaS offerings and the corresponding localized price structures defined in Paddle. ### Manage customer lists Pulls an array of IDs for every customer account managed through Paddle, useful for bulk operations or reporting. ## Use Cases ### Investigating a mysterious failed payment. A customer reports they were charged twice, but can't find the proof. They ask their agent to check the ledger. The agent runs `list_transactions` filtered by date, finds two transactions (one marked 'Paid,' one marked 'Prorated'), and uses `get_transaction_details` on both IDs to show the customer the exact breakdown of charges. ### A departing client needs their access paused. The account manager talks to their agent: 'Pause sub_clientxyz for 30 days.' The agent runs `pause_subscription`, which updates the status and prevents billing until the planned reactivation date. This avoids accidental cancellations. ### Checking pricing before a new regional launch. A dev asks their agent: 'What's the price for Product B in Germany?' The agent runs `list_catalog_products` to find the ID, then uses `list_catalog_prices` to retrieve the localized checkout and tax-inclusive definition for that region. ### Preparing a list of high-risk accounts. RevOps needs to audit all users whose plans are about to lapse. The agent runs `list_subscriptions`, filters by status (e.g., 'past_due'), and uses `get_customer_details` on the resulting IDs to pull the associated tax ID for compliance. ## Benefits - **Instant Billing Audit:** You don't need to navigate the Paddle portal. Use `list_transactions` or `get_transaction_details` to pull specific payment records—like a proration charge from six months ago—and get the data instantly for your agent to analyze. - **Precise Subscription Control:** Don't just guess if a plan is active. Run `get_subscription_details` to confirm the next billing date and status, or use `pause_subscription` when you need temporary service interruption without canceling the account. - **Tax Compliance Verification:** Dealing with tax boundaries shouldn't be guesswork. By calling `list_catalog_prices`, your agent retrieves localized pricing definitions and tax-inclusive amounts, ensuring billing accuracy before a user even checks out. - **Bulk Customer Visibility:** Need to check 50 accounts? Instead of running 50 manual searches, use `list_customers` to get the IDs, then batch run `get_customer_details` to gather all necessary tax and contact data for compliance reports. - **Full Lifecycle Management:** From listing products with `list_catalog_products` to cancelling a plan using `cancel_subscription`, this single server handles the entire billing lifecycle. Your agent moves from catalog view straight into account management in one session. ## How It Works The bottom line is: it turns complex, multi-step billing dashboard actions into simple, reliable tool calls from chat. 1. Subscribe to the server and provide your necessary Paddle API Key. 2. Your AI client calls a tool (e.g., `list_transactions`) specifying required parameters like dates or IDs. 3. The server executes the corresponding Paddle API call, returning structured JSON data directly to your agent. ## Frequently Asked Questions **How do I check if a customer's subscription status changed recently using list_transactions?** You can use `list_transactions` and filter the results by type (e.g., 'cancellation') or date range. The transaction record will show whether the payment was for renewal, proration, or an adjustment. **Can I pause a subscription using the get_subscription_details tool?** No. `get_subscription_details` only retrieves data; it's read-only. To change the status, you must use the dedicated `pause_subscription` tool. **What is the difference between list_customers and get_customer_details?** `list_customers` gives you a raw array of IDs for all accounts. You need to run `get_customer_details` on each ID individually if you want specific information like tax boundaries. **Do I need the API key just for list_catalog_prices?** No, you'll need your Paddle API Key for virtually every tool. It authenticates your agent to perform any billing action or data read from the platform. **When running list_transactions, what specific Paddle API scopes must my AI client have for full read access?** Your agent needs 'read' scope permissions. This ensures your client can pull historical data without failing due to insufficient access rights. It covers viewing payment status, proration details, and ledger entries. **If I run list_catalog_products, how does the server help me get corresponding localized pricing using list_catalog_prices?** You must call these tools in sequence. The agent first uses `list_catalog_products` to gather product IDs, and then passes those IDs to `list_catalog_prices`. This lets you link specific products to their exact tax-inclusive price points. **When calling list_subscriptions, what should my AI client do if the returned data set is extremely large or hits a rate limit?** The server handles standard API pagination. Your agent must check for any `next_page` tokens in the response payload. This ensures you pull all subscription records and don't stop after hitting an artificial data cap. **Does get_transaction_details include specific, localized sales tax calculations from Paddle?** Yes, it pulls detailed ledger entries that specify the exact jurisdiction and applicable tax rate for that transaction. This is critical for finance teams evaluating native transactional tax boundaries. **Can I cancel a customer subscription directly from chat?** Yes. The agent leverages the `cancel_subscription` tool to stop recurring plans natively. You can instruct the agent to cancel it "immediately" or "at the next_billing_period" according to Paddle's API logical boundaries. **How do I fetch the exact localized checkout prices?** The `list_catalog_prices` query extracts the complete Price definitions from your Paddle system. It details the billing frequency, currency boundaries, tax-inclusiveness flags, and item descriptions seamlessly. **Is Paddle Classic Supported or is this for Paddle Billing?** This integration targets the modern Paddle Billing REST API which leverages robust structural objects (like Customers, Businesses, and Subscriptions) ensuring clean MoR tax boundaries and granular item mappings.