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

# Build with Claude Code

Use Claude Code to integrate Paddle — install the MCP servers, add Paddle conventions to your CLAUDE.md, and ship checkout, subscriptions, and webhooks from your terminal.

---

[Claude Code](https://claude.com/claude-code) integrates with Paddle through MCP servers and a project `CLAUDE.md` file. The docs MCP server keeps Claude Code grounded in current Paddle documentation; the Paddle MCP server lets it read and act on your account. A `## Paddle integration` section in your CLAUDE.md tells Claude Code what conventions to follow whenever it touches Paddle code.

This guide focuses on the Paddle-specific workflow. For full MCP setup details across other clients, see the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) and [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) reference pages.

## Before you begin

- A Paddle [sandbox account](https://developer.paddle.com/sdks/sandbox.md) and [API key](https://developer.paddle.com/api-reference/about/api-keys#create-api-key.md).
- Claude Code installed (`npm install -g @anthropic-ai/claude-code`).
- A project that already uses or will use a Paddle SDK.

## 1. Install the Paddle MCP servers {% step=true %}

Run both commands 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
```

```bash
claude mcp add --transport http paddle-docs https://paddlehq.mcp.kapa.ai
```

The first command registers the Paddle MCP server (read and act on your account). The second registers the docs MCP server (current Paddle documentation).

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

You may be prompted to authenticate with Kapa.ai the first time you use the docs MCP server.

## 2. 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. Add this near the bottom of your existing `CLAUDE.md`:

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

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

With both MCP servers connected and your CLAUDE.md updated, ask Claude Code to scaffold the 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 will plan first, then use the Docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and write code that matches your CLAUDE.md conventions.

## Example workflows

```markdown {% wrap=true %}
Audit this Paddle integration. Use the paddle-docs MCP server to confirm best practices, then review my webhook handler, environment switching, and error handling. Tell me what to change and why.
```

```markdown {% wrap=true %}
Investigate why customer sarah@example.com's last payment failed. Use the paddle MCP server to look up her subscription history, payment attempts, and current payment method. Recommend a fix but don't execute anything destructive without my approval.
```

```markdown {% wrap=true %}
Add usage-based billing to my AI app. Base plan is $20/mo plus $0.001 per generation. Use the paddle-docs MCP server to confirm the right pricing model, then create the products and prices in my sandbox account, and generate the metering code that adds custom items to the upcoming transaction.
```

## Optional: skills for recurring workflows

If you find yourself running the same Paddle workflow often — onboarding enterprise customers, reconciling invoices, simulating webhook events — you can codify it as a [skill](https://code.claude.com/docs/en/skills) in `.claude/skills/`.

A simple `paddle-onboard-enterprise/SKILL.md` might describe the steps for setting up a custom-priced enterprise customer (create the customer, set up custom prices, configure manual invoicing, preview the first invoice). Skills give Claude Code a reusable blueprint without bloating your CLAUDE.md.

## Best practices

- **Mention the relevant MCP server explicitly.** "Use the paddle-docs MCP server to check X" works better than hoping Claude Code calls it on its own.
- **Ask for a plan first.** For complex integrations, prompt Claude Code to draft a plan before writing code. Approve, then run.
- **Be specific.** Concrete pricing, event names, and entity IDs work better than vague descriptions.
- **Review every Paddle MCP action.** Claude Code shows pending tool calls before executing — review them, especially anything destructive.
- **Sandbox-only credentials in MCP config.** Never register a live API key in a shared environment.

## Troubleshooting

{% accordion %}
{% accordion-item title="MCP server not registering" %}
Run `claude mcp list` to see registered servers and their status. If the Paddle MCP is missing or errored, re-run the install command and check that your API key is valid.
{% /accordion-item %}
{% accordion-item title="Agent ignores Paddle conventions" %}
Confirm `CLAUDE.md` is at the project root and that the `## Paddle integration` section is present in the file Claude Code is reading. Run `/memory` in Claude Code to inspect what it's loaded.
{% /accordion-item %}
{% accordion-item title="Docs MCP server returns no results" %}
You may have been logged out of Kapa.ai. The first request after expiry typically prompts a re-authentication. Check **Settings** in your Claude Code config for the auth state.
{% /accordion-item %}
{% accordion-item title="Agent generates outdated Paddle syntax" %}
Prompt explicitly: *"Use the paddle-docs MCP server to check the current syntax before generating this."* If you see this often, add an explicit rule to your CLAUDE.md.
{% /accordion-item %}
{% /accordion %}