> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# 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.

---

[Claude Code](https://code.claude.com/docs/en/overview) 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 [sandbox account](https://developer.paddle.com/sdks/sandbox.md)
- A [sandbox API key](https://developer.paddle.com/api-reference/about/authentication.md) with any permissions you plan to use.
- Claude Code installed.
- A project, with a Paddle SDK installed.

## Install the Paddle plugin {% step=true %}

The Paddle plugin bundles [Paddle agent skills](https://developer.paddle.com/sdks/ai/agent-skills.md) with the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md). Agent skills add drop-in instructions for Paddle-specific workflows, while the docs MCP gives Claude real-time access to the latest Paddle docs for troubleshooting and planning.

Inside Claude Code, run:

```bash
/plugin marketplace add PaddleHQ/paddle-agent-skills
/plugin install paddle@paddle-agent-skills
```

Claude Code automatically picks the relevant skill as you work. For example, `paddle-webhooks` when you ask it to set up webhook handling, `paddle-checkout-web` when adding checkout to a page, and so on.

To update later, run `/plugin marketplace update paddle-agent-skills`.

## Install the Paddle MCP server {% step=true %}

The [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) lets Claude Code create and update entities in your Paddle account on your behalf.

Run this command from your terminal. Replace `YOUR_API_KEY` with a sandbox API key.

```bash
claude mcp add paddle -- npx -y @paddle/paddle-mcp \
  --api-key=YOUR_API_KEY \
  --environment=sandbox \
  --tools=non-destructive
```

{% callout type="warning" %}
Use a sandbox API key while you're getting started. The `--tools=non-destructive` scope lets the agent create and read, but not update or archive. Widen to `all` only when you trust the workflow.
{% /callout %}

For manual setup, see the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) reference page.

## Add Paddle conventions to your CLAUDE.md {% step=true %}

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.

```markdown {% title="CLAUDE.md" wrap=true %}
## 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, cancelling subscriptions), ask for explicit confirmation before calling the `paddle` MCP server.
- API keys and webhook secrets live in environment variables — never inline credentials into code.
```

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

## Prompt your first integration {% step=true %}

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 {% wrap=true %}
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 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.**
  Never commit API keys. Add `.cursor/mcp.json` to `.gitignore` if it contains secrets.
- **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.