Use AI to manage pricing, billing, and integrations

The Paddle Model Context Protocol (MCP) server enables AI systems to interact with your Paddle account.

Instead of navigating to the dashboard or accessing the API directly, your team can now ask AI assistants to perform tasks in natural language to achieve complex pricing, billing, sales, support, and integration workflows.

The Paddle MCP server is still under development and is subject to change at any time. Review any action taken by the AI assistant before and after execution. Assistants are conversational and may not always follow your instructions as expected.

How it works

Model Context Protocol (MCP) is an open standard that enables AI systems to securely connect and interact with external services and data sources. It acts as a "universal remote" that exposes data (resources) and actions (tools) to Large Language Models (LLMs), so they're empowered to do more than only chat.

There are two different MCP implementations:

• Clients that use MCP servers, like Claude, Cursor, or an AI chatbot you built.
• Servers that expose data and actions to the clients.

Paddle offers an MCP server. It lets AI agents and assistants access your Paddle account data and take actions immediately, so you can:

• Manage your full pricing

  Build complete pricing models for different product types, with regional pricing and migrations using AI assistants.

• Debug billing issues

  Investigate failed payments, identify billing inconsistencies, and resolve provisioning problems end-to-end.

• Understand company performance

  Generate custom reports and analyze transaction patterns, refund trends, and revenue metrics to inform business decisions.

• Handle subscription lifecycles

  Process upgrades, downgrades, pauses, cancellations, and adjustments with intelligent recommendations based on customer history and business policies.

• Onboard enterprise customers

  Parse complex quotes, create custom pricing, set up manual invoicing, and migrate customers with proper proration.

• Integrate and test Paddle

  Generate integration code for your stack, configure webhooks, create test simulations, and debug delivery issues.

Everything that's exposed to the MCP server is automatically added to the conversation's context, so follow-up questions can be asked.

Tools

Tools are the actions that the AI assistant can perform. Each tool maps to a Paddle API operation, so parameters and functionality match what's available in the API reference.

By default, only non-destructive tools are loaded. This means that the AI assistant can only use tools that don't edit or delete any records.

This is intentionally designed to reduce the chance of dangerous or destructive actions being taken in error, reduce the tokens you spend, and improve performance.

You can further limit or increase the tools the AI assistant can access by setting the tools option when installing the MCP server:

Some clients, like Claude Desktop and Cursor, let you toggle the availability of registered tools in their settings screen. If you'd prefer to control availability there, set tools to all and toggle as needed.

Before you begin

You must create an API key for the LLM to use when making calls to the Paddle API through the MCP server. The API key must have the respective permissions based on the tools you choose to let the AI assistant use, or requests fail with a forbidden error (403).

Your API key grants access to your Paddle account. Keep it secure and only use it with trusted AI agents and assistants.

Install the MCP server

The MCP server uses stdio transport and runs locally on your machine. No remote access is possible yet.

Setting up the Paddle MCP server varies slightly depending on which AI client you're using.

AI assistants using the MCP server can access your Paddle data. Only use assistants that you trust.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1{
2  "mcpServers": {
3    "paddle": {
4      "command": "npx",
5      "args": [
6        "-y", 
7        "@paddle/paddle-mcp", 
8        "--api-key=YOUR_API_KEY", 
9        "--environment=sandbox",
10        "--tools=non-destructive"
11      ]
12    }
13  }
14}

Use the MCP server

Once you've set up the Paddle MCP server with your MCP client, tools are registered and available for the AI assistant or agent to use.

AI assistants may interpret requests differently across sessions. Always review generated code, data changes, and financial transactions before accepting or applying.

Some MCP clients, like Claude and Cursor, require you to manually accept each tool call before they run. Always keep this setting enabled and always review the details of the tool calls before executing them, especially when using tools which edit, archive, or delete entities.

Manage your pricing

Products and prices determine what's being sold to customers as part of your catalog, making up the core of your pricing model.

Instead of manually creating products and prices through the dashboard or API, you can describe your pricing structure to your AI assistant in natural language. The assistant creates the appropriate products and related prices, implements regional pricing strategies, and helps you evolve your catalog over time, including migrating customers from old plans to new ones while maintaining business continuity.

Managing a complete pricing model requires careful planning. Being specific about products, how they're priced, and your migration strategy helps the AI assistant accurately implement and evolve your pricing over time.

Flow

To manage your pricing model using natural language, follow these steps:

1. Describe your pricing structure or changes

   Provide a detailed description of products and their pricing structure. Include product names, descriptions, pricing tiers, billing cycles, trial periods, and any regional pricing needs.

2. Add your migration strategy

   If you're introducing a new pricing model, be explicit about how you want to handle migrating existing customers so the AI assistant creates the correct prices or discounts to handle grandfathering when needed.

3. Review created or updated products

   After the assistant creates or updates products, review them to ensure they match your requirements. Check names, descriptions, tax categories, and archive status.

4. Review created or updated prices

   Verify that prices are correctly associated with products, have the right amounts, billing cycles, regional overrides, and any quantity limits. For migrations, confirm that grandfather pricing and discounts are configured correctly.

Best practices

When asking the AI to manage your pricing model:

• Be specific about product types

  Say what type of products you need, like subscription plans, per-unit products, or one-time charges, so the AI can create them correctly. For per-unit products, specify the quantity limits.

• Define clear billing cycles

  Specify how often you want to bill for each product, like monthly or yearly, and whether you need trial periods.

• Provide thorough price details

  Include specific amounts, currencies, and any regional price overrides plus tax modes to ensure accurate pricing. For regional or international expansion, mention target markets and whether you want purchasing power parity adjustments.

• Structure your request logically

  Organize your request by product types, then prices, using a table format where appropriate to make the information clear and structured.

• Migrate customers slowly

  When migrating customers to new pricing, manage the migration in steps, only focusing the AI on one task at a time, like identifying those customers, creating any new catalog items, and then updating subscriptions. Consider restricting the scope to a smaller subset of customers and set boundaries.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1Set up a new pricing model for my team collaboration SaaS platform with three main plans and an add-on option.
2
3For our main subscription plans, I want:
4- A Basic Plan for small teams, priced at $29/month or $290/year, with a 14-day free trial.
5- A Pro Plan with more advanced features at $79/month or $790/year, also with a 14-day trial.
6- An Advanced Plan for larger organizations at $299/month or $2,990/year, with the same trial period.
7
8The Basic Plan includes 5 projects, basic reporting, and email support.
9The Pro Plan offers unlimited projects, advanced reporting, priority support, and API access.
10The Advanced Plan adds custom reporting, dedicated support, SSO, and audit logs to the Pro features.
11
12I also need an Additional Seats add-on that customers can purchase between 1-1000 units, priced at $10/month per seat or $100/year per seat. No trial for this add-on.
13
14After you've created everything, confirm they're set up correctly and show me the full list of products and prices in a markdown table.

1
2
3
4
5
6
7
8
9
1We're launching in Brazil, India, Poland, and South Africa. Look at our current product catalog and pricing structure for our three subscription tiers (Basic, Pro, Enterprise).
2
3For each of these markets, I need you to:
41. Research typical purchasing power parity adjustments for SaaS products in these countries
52. Calculate optimal price points that maintain similar perceived value to our US pricing
63. Use appropriate local currencies (BRL for Brazil, INR for India, PLN for Poland, ZAR for South Africa)
74. Create new price entities with country-specific overrides for each product
8
9After creating the prices, preview what a customer in each country would actually pay ensuring the tax mode is set to what the country expects, and show me a comparison table.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1We're retiring our 'Starter' ($19/mo) and 'Professional' ($49/mo) plans and consolidating into a single 'Growth' plan at $59/month. Here's what I need:
2
31. Create the new Growth product and monthly/annual prices ($59/mo or $590/yr)
42. Find all active customers currently on Starter and Professional plans
53. Apply recurring discounts to customer subscriptions that will maintain their current pricing for 6 months (grandfather pricing)
64. Archive the Starter and Professional products so new customers can't sign up
7
8Before executing, show me:
9- How many customers are on each legacy plan and their current pricing
10- The specific discounts that will be created for each plan
11- A preview of what each customer will pay after the migration
12- A preview of what the financial impact will be over the next 12 months (month by month)
13
14Once I approve, apply the discounts and archive the old products. Break it down into small steps to tackle individually.

Debug and resolve billing issues

When customers report billing issues or payment failures, your first priority is to understand the cause. Using the MCP server, your AI assistant can gather and analyze transaction data, subscription records, payment attempts, and customer account details. This lets it pinpoint issues such as failed transactions, expired payment methods, or inconsistencies in subscription information quickly and accurately.

After identifying the source of the problem, the assistant can move from diagnosis to action. It can gather the relevant billing information, explain the situation clearly to customers, and either automatically resolve issues or recommend next steps to take.

Best practices

When asking the AI to help debug and resolve issues with your Paddle data:

• Provide specific identifiers

  Always start by gathering specific identifiers, like customer email or Paddle IDs to include in your question so the assistant can more easily identify the relevant records.

• Be specific about your investigation goals

  Describe what you need to understand about the billing issue. State its nature, like payment failures, unexpected charges, or subscription status problems. Explain what you're trying to do, like explaining a charge to a customer or diagnosing why payments are failing.

• Mention relevant time periods

  For recurring billing issues, specify relevant time frames, like "last month" or "since January," to help narrow down when the problem started. The more specific the time period, the better.

• Ask about related information

  If you need to understand connections between different aspects, like how subscription changes affected billing, explicitly ask about these relationships in your question.

• State when you need comprehensive data

  When debugging issues that require examining patterns or multiple records, explicitly ask to "see all related transactions" or "check all subscriptions for this customer" to ensure you get a complete picture, rather than just the most recent or default records.

• Request step-by-step investigation

  For complex billing issues, ask the assistant to "think step-by-step" and investigate each aspect systematically. This helps identify root causes and ensures nothing is missed.

• Specify resolution authority

  Make it clear whether the assistant should only investigate and recommend actions, or if it should automatically resolve issues it identifies. For sensitive operations like refunds, you may want approval before execution.

Examples

1
2
3
4
5
6
7
8
9
1Help me investigate why customer sarah@example.com had a failed payment. Think step-by-step and check their subscription status, recent transactions, and payment method information. I need to understand:
2
31. When the payment failed and what error occurred
42. If this is a recurring issue or first-time failure (review last 3-6 months of transactions)
53. What subscription plan they're on and its current status
64. If there are any scheduled changes on their subscription
75. Any details that can be given on the payment method for the failed attempt
8
9If you find multiple recent failures, check if other subscriptions for this same customer have similar issues.

1
2
3
4
5
6
7
8
9
10
1A customer is confused about their latest invoice amount. They have subscription ID sub_01h84k1q63jyrbyswphfhfbase and expected to pay $99/month, but were charged $149.
2
3Find their most recent transaction and check:
41. If there were any subscription changes during this billing period
52. Whether proration was applied
63. If they added any items, add-ons, or one-time charges
74. If there were any adjustments or discounts
85. The detailed breakdown of line items
9
10I need to explain clearly to the customer why their bill was higher than expected and what exactly they paid for.

1
2
3
4
5
6
7
8
1We have a customer who claims their subscription shouldn't be canceled but shows as canceled in their account. Their email is john@example.com.
2
3Check their subscription history to determine:
41. When the subscription was canceled
52. What transaction or event occurred around the cancellation time
63. If there were any failed payment attempts before cancellation
74. If there's any scheduled change that might have triggered this
85. What their billing history looks like before cancellation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1Customer John Smith (john@company.com) says he was charged twice for his November subscription. Investigate what happened:
2
31. Find all November transactions for this customer
42. Identify if there are truly duplicate charges or if this is expected (like a mid-cycle change)
53. Determine the root cause of any duplicate
64. If it's a legitimate error, calculate the refund amount needed
7
8If you confirm it's a duplicate charge, go ahead and:
9- Issue a refund for the duplicate amount
10- Document the reason in the adjustment
11- Fix any subscription scheduling issues to prevent recurrence
12- Generate a credit note
13
14Then draft an email to the customer explaining what happened, why it occurred, what you've done to fix it (if anything), and how you've prevented it from happening again (if applicable).

Understand company performance

Reports provide insights into transaction history, adjustments, and catalog changes. Using the MCP server, your AI assistant can generate these reports and quickly analyze performance data.

All reports can be filtered to return the data you need so the AI assistant can conduct proper analysis for the purpose of growth or compliance and understand where you're succeeding or struggling to make immediate improvements.

Reports are generated as CSV files and aren't immediately available to the AI assistant. Download the CSV from the email sent to your Paddle account's main email address, or wait for the report to be generated and then ask the AI assistant to fetch it using the get_report_csv MCP tool.

Flow

To generate reports and analyze financial data, follow these steps:

1. Request the report or analysis

   Prompt the AI to generate the report or perform the analysis. Give as much detail as possible about what you need, detailing your aims and business goals so the right report type, data fields, and analytical approach are selected.

2. Download the report

   AI assistants can fetch the report using the get_report_csv tool so you can download it from the given url. However, you may need to wait for the report to be generated before this is available. Resend the request to check the status, or wait for the email with the report link to be sent to the main email address on your Paddle account.

3. Upload to the AI assistant

   Once you've downloaded the report, upload it to the AI assistant to give it access to the data.

4. Fetch related entities

   If the analysis can be enhanced by real-time Paddle data not given in the report, give specifics of what's needed and repeat your aims to the AI assistant which may be lost in context.

5. Review insights and take action

   The assistant provides insights, identifies trends or issues, and may recommend or execute actions like updating records, creating adjustments, or flagging items for manual review.

Best practices

When asking the AI to manage your financial operations:

• Specify the report type

  Different report types expose different data fields and insights. Being specific helps the AI immediately know which dataset to query, like transactions for revenue analysis or adjustments for refund patterns.

• Include clear date ranges

  Date ranges determine the scope of your analysis and keep reports focused on relevant time periods. This helps improve both report generation time and analysis clarity.

• Mention any filters

  Filters narrow your dataset to exactly what you need, removing noise from your analysis. Common filters include statuses, types, and currencies.

• Describe what you're trying to analyze

  Explaining your analysis and business goals helps the AI choose appropriate fields and groupings not obvious from specifying only filters, pull additional entity details where needed, and prioritize what data matters most.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
1Generate a transaction line items (`transaction_line_items`) report for the past 6 months, filtering for `completed` and `canceled` statuses across all currencies. I need to optimize our pricing strategy by analyzing transaction data to determine:
2
31. Geographic performance: Which prices and products perform best in different regions?
42. Price point effectiveness: Which specific price points generate the most revenue?
53. Billing frequency patterns: Compare performance of monthly vs. annual billing options
64. Product tier analysis: Identify which product tiers have the highest adoption and revenue
7
8After analyzing the data, please:
9- Identify our 3 highest-revenue and lowest-revenue product/price combinations
10- Highlight any pricing anomalies across different currencies or regions
11- Recommend potential price adjustments based on actual transaction patterns
12- Suggest which product tiers might benefit from restructuring based on purchase behavior
13
14Our goal is to increase overall revenue by optimizing our pricing model. I'm particularly interested in understanding customer purchasing patterns across different currencies and whether our current price points are effectively capturing value in each market we serve.

1
2
3
1Create an adjustments report covering all of Q1 2025 (January through March) that includes both refunds and chargebacks with `completed` status. 
2
3Only consider transactions above $100 USD equivalent. I'm trying to understand the root causes of customer dissatisfaction by correlating adjustment reasons with specific products and customer segments. This analysis helps our product team prioritize feature improvements to reduce our refund rate before our next investor meeting.

1
2
3
1Show me a report of all active and archived products updated since January 1st, 2025. Include all price points across all supported currencies. 
2
3I need to conduct a comprehensive analysis of our pricing structure to identify inconsistencies in our regional pricing strategy and opportunities for price optimization. This supports our expansion planning for new markets in Q3 and ensures our pricing reflects current market conditions.

Handle subscription and lifecycle changes

Subscriptions are the foundation of recurring revenue businesses. Customers frequently need to make changes to their subscriptions, upgrading to access more features, downgrading due to changing needs, pausing temporarily, or canceling entirely. Using the MCP server, your AI assistant can help you quickly process these requests by investigating customer context, previewing financial impacts, and executing changes with appropriate proration.

They can even go a step further to identify growth and retention opportunities, and then take immediate action to capitalize on them, like identifying conversion opportunities during trials, creating targeted retention offers for at-risk customers, and recommending refund decisions based on history.

Best practices

When asking the AI to help with subscription changes:

• Provide clear business policies

  Share your guidelines and business policies with the assistant so it can handle different situations consistently, like refund and downgrade policies, when to offer discounts, how to handle high-value customers, what requires manager approval, and proration preferences.

• Request customer context

  Ask the AI to investigate customer history, lifetime value, and previous interactions before recommending actions. This ensures recommendations are appropriate for each customer's relationship with your business.

• Segment customers for different treatment

  When processing multiple requests, describe how different customer segments should be handled, like offering discounts to new trials but not established customers, or processing high-value accounts with extra care.

• Specify your search criteria

  When asking the AI to find subscriptions needing attention, be specific about criteria like "trials ending in 7 days" or "subscriptions past_due for more than 3 days" so it knows exactly what to look for.

• Always preview financial impacts

  For subscription changes that affect billing, ask the AI to preview the financial impact before executing changes. Assistants can use the preview_subscription_update tool to see exactly what customers would be billed, credited, or refunded.

• Expect approval requests

  For sensitive operations like refunds, adjustments, or cancellations, the assistant presents its analysis and recommendation, then waits for your explicit approval before proceeding. This ensures you can review the reasoning and intervene before any financial impact occurs.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
1I want to reach out to trials ending in the next 7 days to improve conversion. Help me segment them:
2
3First, list all subscriptions with status 'trialing' which are either billed in the next 7 days, or have no next billed date set but whose trial period is ending in the next 7 days.
4
5Then for each subscription:
61. Get the customer details
72. Get their next transaction preview to see what they'll be charged (if anything)
8
9Segment them into two groups:
10- Group A: Will be billed and therefore has payment method (ready to convert)
11- Group B: Won't be billed and therefore has no payment method (needs incentive)
12
13For Group B, create a 15% recurring discount valid for first 3 months.
14
15Provide me with:
161. List of customers in each group with email addresses and upcoming charges (if any)
172. The discount code created for Group B
183. Total MRR at risk if all trials don't convert
194. Draft email templates I can use for each segment

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1A customer (email: sarah@example.com) is requesting a full refund for their annual subscription purchased 3 months ago. They say the product didn't meet their needs.
2
3Investigate and recommend action:
4
51. Get their complete customer history:
6   - How long they've been a customer
7   - Total amount paid
8   - Usage patterns (from external sources)
9   - Any previous refund requests 
10   - Any support tickets raised (from external sources)
11   - Lifetime value
12
132. Get the subscription and transaction details:
14   - What plan they purchased and price paid
15   - Current subscription status
16   - Remaining time on their annual subscription
17   - Whether they've used any features or shown engagement
18
193. Based on this context, recommend one of these actions:
20   - Full refund: If this is their first request and they're a short-term customer

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1I have three customers requesting subscription changes. Help me handle each appropriately:
2
3Customer 1: Upgrade Request
4- Email: john@startup.com
5- Current plan: Basic ($29/mo)
6- Wants: Pro plan ($79/mo)
7- Timing: Wants to upgrade immediately
8
9Customer 2: Downgrade Request  
10- Email: sarah@enterprise.com
11- Current plan: Enterprise ($299/mo)
12- Wants: Pro plan ($79/mo)
13- Timing: End of current billing period
14- Reason: Team size decreased
15
16Customer 3: Temporary Pause
17- Email: mike@consulting.com
18- Current plan: Pro ($79/mo)
19- Wants: Pause for 3 months (between client projects)
20- Willing to resume afterward

Onboard and manage enterprise customers

Enterprise customers often require onboarding workflows with manual invoicing, custom pricing, multiple contacts, and complex billing terms. Managing these customers manually through the dashboard can be time-consuming and error-prone, especially when handling quotes, contracts, and migrations from self-serve plans alongside other systems.

Using the MCP server, your AI assistant can orchestrate the entire enterprise onboarding process, both within and outside of Paddle. It can parse complex quotes and customer details to convert them into Paddle entities, configure specific payment terms ensuring all billing requirements are met, migrate self-serve customers to manually invoiced enterprise plan, and generate the necessary documentation for your sales and finance teams.

Enterprise onboarding often involves custom pricing and terms that differ from your standard catalog. Items created by AI assistants in Paddle are often custom and non-listed in your standard catalog as a result. Ensure this is what you expect.

Flow

To onboard enterprise customers or migrate them from self-serve plans, follow these steps:

1. Provide contract or quote details

   Share as much information as possible from your CPQ (Configure, Price, Quote) tool, contract, or enterprise agreement documents. The assistant can validate that the setup matches approved business terms and catch potential issues before they occur.

2. Provide additional information

   Include customer and business details like tax ID, legal entity address, email address, and information on the jurisdiction they're in. Manual invoicing currently supports USD, EUR, and GBP, so specify which applies to the customer.

3. Preview and review

   Before finalizing, ask the assistant to preview the full transaction including amounts, currencies, customer details, and proration details, if migrating from an existing subscription. Verify that the amounts, terms, and structure match your signed contract or quote.

4. Execute the onboarding

   Once approved, the assistant creates all necessary Paddle entities, sets up manual invoicing with the correct payment terms, generates an invoice and payment link if required, and provides these to your team or customer.

Best practices

When asking the AI to onboard enterprise customers:

• Provide complete contract and sales context

  Connect the assistant to other MCPs or pull and include data from other APIs and sources, like your CRM, CPQ tools, contracts, or enterprise agreement documents. This includes pricing and discount rules, sales playbooks, billing terms, payment schedule, approval workflows, and any special arrangements. The more given, the better the validation against policies and terms.

• Clarify custom pricing structure

  If pricing differs from your standard catalog, be explicit about whether you need entirely new price entities or if you're using existing products with custom pricing for this customer. This keeps your catalog clean and prevents enterprise pricing from being accidentally used elsewhere.

• Request migration handling for existing customers

  When upgrading self-serve customers to enterprise, specify how to handle their existing subscription, including proration, billing timing, and any credits they should receive. Remember to include their email and address.

• Preview before finalizing

  Always ask the AI to preview the complete setup and first invoice before executing. This is especially important for large contracts to ensure everything matches the agreement and your guidelines, and there are no surprises.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1### Onboarding a new enterprise customer
2
3We just closed Example Inc. Here's the signed contract and setup details:
4
5From signed Master Services Agreement:
6- Customer: Example Inc.
7- Legal entity address: 123 Business Park, New York, NY 10001, USA
8- Tax ID: 12-3456789
9- Billing contact: Bob Smith, AP Manager, bob@example.com, +1-212-555-0100
10- Technical contact: Jane Doe, CFO, jane@example.com, +1-212-555-0101
11
12From approved enterprise quote (Quote #ENT-2025-089):
13- 100 user licenses @ $45/user/month = $54,000 annually
14- Premium Support package: $6,000/year (flat fee)
15- Total annual value: $60,000
16- Billing: Annual invoices in USD
17- Payment terms: Net 45 days
18- Contract start: December 1, 2025
19- Pricing tier: Enterprise Custom (not for catalog)
20

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1We have a signed enterprise deal for Startup Inc. They're currently a self-serve customer, and we need to migrate them to the new enterprise plan.
2
3From Salesforce CPQ Quote #Q-2025-1234:
4- Customer: Startup Inc
5- Contact: Sarah Chen, COO, sarah@startup.com  
6- Address: 500 Market Street, San Francisco, CA 94105, USA
7- Quote details:
8  - 50 user licenses @ $35/user/month = $1,750/month
9  - One-time implementation fee: $2,500
10  - Billing: Monthly invoices, Net 30 payment terms
11  - Start date: Immediate
12  - Approved pricing tier: Enterprise Custom
13
14From our enterprise sales playbook:
15- Migrate immediately with proration
16- Create custom (non-catalog) enterprise pricing specific to this customer
17- Switch from automatic to manual invoicing
18
19What I need you to do:
20

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1I need to create a custom enterprise quote for a prospect. Here are their requirements:
2
3Prospect Details:
4- Company: TechScale GmbH
5- Location: Munich, Germany
6- Contact: Hans Mueller, CTO, hans@techscale.de
7- They want to start January 1, 2026
8
9Pricing Requirements:
10- Base platform: 25 users at €40/user/month
11- Enterprise features bundle: €500/month flat fee
12- Additional API calls: 5M calls/month at €200 per 1M calls = €1,000/month
13- Priority support: Included at no extra charge
14- Total monthly: €2,500
15- They prefer annual billing: €30,000/year with 2 months free (so €25,000 annual price)
16- Payment terms: Net 30 days
17- Invoice in Euros
18
19What I need:
201. Check if we have products/prices set up for these items, if not, tell me what needs to be created

Integrate and test Paddle

Implementing Paddle Billing in your app requires setting up products and prices, building checkout flows, handling webhook events for provisioning, storing subscription data, and thoroughly testing all scenarios. Traditionally, this involves reading documentation, writing integration code, manually testing webhooks, and debugging issues across environments.

Using the MCP server, your AI assistant can build and test complete Paddle integrations end-to-end, turning days or weeks into minutes.

The AI generates frontend and backend code while using the Paddle MCP tools to set up frontend authentication, create products, configure webhooks, create test simulations, debug issues by querying Paddle data, and replay failed webhook events to fix issues.

It can even work with other systems and tools to create database schemas, set up local testing environments with tunnels, migrate from other billing platforms, and debug issues by correlating errors across systems.

Flow

To integrate Paddle into your app with AI, follow these steps:

1. Ensure access to commands, systems, and tools

   Integration work often requires access to multiple systems beyond Paddle, like your codebase, database, error tracking tools, and local development environment. Make sure your AI assistant has the appropriate access and MCP tools, commands, or integrations configured to work across these systems.

2. Define your integration requirements

   Describe your stack (framework, database, hosting), how customers should checkout, and how you'll handle provisioning. Be specific about your tech stack and requirements so the AI agent generates appropriate code.

3. Set up products and pricing in Paddle

   Have the AI assistant create your product catalog in Paddle or review existing products in advance. Be clear on your requirements for your pricing model and how access and provisioning works.

4. Generate integration code

   The AI assistant creates the necessary code components, like pricing pages, checkout flows with Paddle.js, webhook endpoints, database schemas for storing billing data, and middleware for feature gating based on subscription status.

5. Verify the webhook handler implementation

   Ensure the webhook secret is stored securely in environment variables. If the integration is using a supported SDK, ensure the implementation uses the SDK's unmarshal function to verify the webhook signature correctly.

6. Set up local testing environment

   Once implemented, ask the AI assistant to configure webhook testing using tunnels to your local development environment, like with Hookdeck, and to create and run Paddle webhook simulations to verify webhooks are being received and processed correctly for different edge cases and scenarios.

7. Debug and refine

   Use the AI to diagnose any issues by examining webhook logs, debugging payment flows, checking for missing or failed webhook deliveries, and replaying real or simulated webhook events when needed.

8. Migrate from other platforms

   If moving from another billing provider, have the AI help map your existing data to Paddle's structure, create migration scripts, and validate the migration before switching over.

Best practices

When asking the AI to help with Paddle integration:

• Use a sandbox environment

  Sandbox accounts are for testing your integration without affecting your production data. Use them in your local and staging environments to test your integration while building and testing. Ensure your API key and environment set for the MCP installation are sandbox credentials.

• Go task-by-task

  Ask the AI assistant in IDEs like Cursor to break down the tasks step-by-step. Use features like 'Plan' mode to generate a checklist of steps to take and MCP tools to use for each task. Alternatively, offer individual prompts for each phase to guarantee focus and better results.

• Add Paddle docs as a source

  If your IDE supports it, like with Cursor, index and add Paddle's documentation as a source to the assistant. This helps it understand the Paddle platform with most recent information.

• Be specific about your tech stack

  Include your framework (Next.js, Rails, Django, etc.), database (PostgreSQL, MySQL, Supabase, etc.), hosting platform, and any relevant libraries. This ensures generated code matches your stack and conventions.

• Give code examples or start with a template

  Paddle offers a Next.js starter kit and SDKs with examples of how to integrate, including webhook verification. If you use other frameworks, start with a template or examples of how you want your code to be structured and implemented to have greater chance of success.

• Request production-ready code

  Ask for proper error handling, security best practices like webhook signature verification, idempotency for webhooks, and appropriate logging. Don't accept quick hacks and instead insist on code you can ship.

• Test webhook handling thoroughly

  Ensure your integration handles all relevant subscription lifecycle events, processes them idempotently to handle duplicates gracefully, verifies the webhook signature, and updates your database correctly. Ask the AI to verify each scenario with webhook simulations.

• Request migration validation

  If migrating from another platform, ask the AI to preview the migration for a small batch first, verify data integrity, and identify any edge cases before running the full migration.

• Use real identifiers in prompts

  When debugging, include actual error messages, transaction IDs, webhook event IDs, and other specific identifiers. This allows the AI to investigate the exact issue rather than working from generic descriptions.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1I'm building a Next.js 14 app with Supabase (PostgreSQL) for database. Create a complete Paddle billing integration with everything I need for production:
2
3Tech Stack:
4- Frontend: Next.js 14 with App Router and Tailwind CSS
5- Backend: Next.js API routes
6- Database: Supabase (PostgreSQL)
7- Auth: Supabase Auth
8
9Pricing Model:
10Create 3 subscription tiers in Paddle with the following structure:
11
12| Plan     | Monthly | Annual     | Projects | Features                    |
13|----------|---------|------------|----------|----------------------------|
14| Starter  | $9      | $90 (-17%) | 3        | Basic analytic access            |
15| Pro      | $29     | $290 (-17%)| 10       | Advanced analytic access, API access    |
16| Business | $99     | $990 (-17%)| Unlimited| White-label, priority support |
17
18All plans include a 14-day free trial
19
20Steps to take:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1My Paddle integration is implemented. Now I need to test the complete webhook flow from Paddle → Hookdeck → my local server → database. This confirms my integration handles the full webhook lifecycle correctly before deploying to production.
2
3Current Setup:
4- Local dev server: http://localhost:3000
5- Webhook endpoint: /api/webhooks/paddle
6- Database: Supabase (Supabase MCP available - optional)
7- Hookdeck CLI installed
8
9Step 1: Start Hookdeck Tunnel
10
11Set up Hookdeck CLI to tunnel webhooks to the local webhook endpoint handling Paddle events.
12
13Step 2: Configure Paddle Webhooks
14
15Once running, grab the Hookdeck webhook URL from the Hookdeck CLI output and configure a notification setting in Paddle:
16- Point to the Hookdeck webhook URL
17- Subscribe to all events handled by my webhook handler
18- Show me the webhook secret so I can add it to my environment variables before proceeding. Pause here.
19
20Step 3: Create Test Webhook Simulation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1Our webhook endpoint was down yesterday (November 2) from 2:00 PM to 4:00 PM UTC, and I'm concerned some customers weren't properly provisioned. Help me fix this:
2
3Investigation:
41. Find all Paddle events that occurred during that 2-hour window
52. Check which notifications failed to deliver
63. Query our database to identify which subscriptions are in an inconsistent state
7
8Recovery:
91. List all customers who should have been provisioned but weren't
102. Replay the failed webhook events in the correct order
11   - Handle dependencies (subscription.created must come before subscription.updated)
123. Verify after each replay that our database updated correctly
13
14Verification:
151. For each affected customer, confirm:
16   - Customer record exists in our database
17   - Subscription is in the correct state
18   - They have the appropriate feature access
19   - Any transactions are recorded
20

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1I'm seeing an unexplained production error in Sentry for user john@example.com: 'Access denied: Cannot access Pro features' and need to correlate it with Paddle data to debug.
2
3Investigation Steps:
4
51. Check Sentry for the error.
6
72. Find this customer in Paddle:
8   - Search for john@example.com
9   - Get their customer ID and subscription details
10
113. Analyze their subscription:
12   - What's the current status and why is it past_due?
13   - Get recent transaction history
14   - Check for payment failures and error messages
15   - See if there's a payment method on file
16
174. Check for systemic issues:
18   - Are there other customers with the same error?
19   - Is this a dunning/payment retry issue?
20   - Or is this a webhook processing bug on our side?

Related pages