For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

Build with Claude Code

Set up Claude Code for the best possible Paddle workflow by installing the Paddle plugin, connecting the Paddle MCP server, and adding a CLAUDE.md file.

AI summary

Set up Claude Code with the Paddle plugin, MCP servers, and CLAUDE.md conventions to use an AI coding assistant for building Paddle integrations.

  • • Install the Paddle plugin from the Claude Code marketplace, which bundles Paddle agent skills with MCP servers for sandbox and live environments
  • • Export Paddle API keys as environment variables (PADDLE_SANDBOX_API_KEY and PADDLE_LIVE_API_KEY) so MCP servers can authenticate requests
  • • Add a Paddle section to CLAUDE.md specifying which SDK to use, how to handle environments, webhook verification methods, and when to prompt for confirmation on destructive operations

Claude Code is an AI-powered coding assistant that helps you build features, fix bugs, and automate development tasks. It works as a CLI, IDE extension, or as part of the Claude Desktop app.

This guide runs through setting up Claude Code for the best possible experience when building with Paddle.

Before you begin

You'll need:

  • A Paddle account that you want to connect to — sandbox, live, or both.
  • If connecting to a sandbox account, a sandbox API key with any permissions you plan to use.
  • Claude Code installed.
  • A project, with a Paddle SDK installed.

Install the Paddle plugin

The Paddle plugin bundles Paddle agent skills with the docs MCP server and Paddle MCP servers.

Open Claude Code, then run:

Shell
/plugin marketplace add anthropics/claude-plugins-community
/plugin install paddle@claude-community

Connect the Paddle MCP servers

The plugin wires up two Paddle MCP servers so the agent can work in both sandbox and live environments. This is useful for porting data from one to the other.

MCP serverURLAuthentication
paddle-sandboxhttps://sandbox-mcp.paddle.com/mcpAPI key
paddle-livehttps://mcp.paddle.com/mcpOAuth or API key

For paddle-sandbox, Claude Code prompts you for a sandbox API key and stores it in your operating system's keychain. Create one at Paddle > Developer tools > Authentication.

For paddle-live, Claude Code opens your browser to authorize with Paddle the first time you use the server. You can also run /mcp to authenticate or check connection status.

Check MCP permissions carefully

A live connection made with OAuth has the same read access as your Paddle user role. You can change this under Paddle > Connectors > MCP. Access to sandbox is determined by its API key permissions, so scope the key to only what the agent needs.

Add Paddle conventions to your CLAUDE.md

Claude Code reads project conventions from CLAUDE.md at the project root. A focused Paddle section tells it which SDK to use, how to handle environments, and how to verify webhooks.

Create a CLAUDE.md file at the project root, or add it to your existing CLAUDE.md file.

CLAUDE.md
## Paddle integration


When writing or modifying code that integrates with Paddle:


- Always check current Paddle documentation via the `paddle-docs` MCP server before suggesting code. The Paddle API and SDKs evolve frequently — do not rely on training data alone.
- Use the official Paddle SDK for the language in use:
  - Node.js → `@paddle/paddle-node-sdk`
  - Python → `paddle-python-sdk` (imports as `paddle_billing`)
  - Go → `github.com/PaddleHQ/paddle-go-sdk/v5`
  - PHP → `paddlehq/paddle-php-sdk`
- All development uses the sandbox environment. Sandbox API keys contain `_sdbx`; sandbox client-side tokens are prefixed with `test_`.
- Always verify webhook signatures before acting on the payload:
  - Node: `paddle.webhooks.unmarshal()`
  - Python: `Verifier().verify(request, secret)`
  - Go: `paddle.NewWebhookVerifier()` with `Middleware`
  - PHP: `(new Verifier())->verify($request, $secret)`
- For destructive account changes (updating prices, archiving products, canceling subscriptions), ask for explicit confirmation before calling the `paddle-sandbox` or `paddle-live` MCP server.
- Use `paddle-sandbox` by default. Only call `paddle-live` when the prompt explicitly mentions live, production, or real customer data.
- API keys and webhook secrets live in environment variables — never inline credentials into code.

Adjust the SDK list to match the languages your project uses. Claude Code will read this every time you start a session.

Prompt your first integration

With the plugin installed, the Paddle MCP server connected, and your CLAUDE.md file in place, ask Claude Code to scaffold a Paddle integration.

markdown
Add a Paddle Checkout integration to this Next.js app. Use the paddle-docs MCP server to look up the current Paddle.js syntax. Then use the paddle-sandbox MCP server to create three products in my sandbox account — Starter ($10/mo), Pro ($30/mo), Enterprise ($300/mo) — and generate a /pricing page that opens checkout for each tier. Wire up a /api/webhooks route that verifies the signature and logs transaction.completed events.

Claude Code plans first, then uses the docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and writes code that matches your CLAUDE.md conventions.

Best practices

  • Mention Paddle and the relevant MCP server explicitly.
    "Use the paddle-docs MCP server to look up X" beats hoping the agent calls it on its own.
  • Use Plan mode first.
    For complex integrations, enter plan mode to draft a plan before writing code. Approve, then run.
  • Be specific in prompts.
    Concrete pricing, event names, and entity IDs work better than vague descriptions.
  • Review changes before applying.
    Claude Code shows pending tool calls before executing. Review every tool call, especially anything destructive.
  • Never commit API keys.
    Keep API keys in environment variables.
  • Create your own skills.
    When you find yourself repeating the same instructions over and over, create a skill to help steer Claude Code. Run /skill-creator to walk through the process with Claude.

Was this page helpful?