Skip to main content
plugin

paddle — Claude Code plugin: features and installation

Connect Claude Code to Paddle Billing guidance and docs, then build payment flows for checkout, subscriptions, and webhooks. The included skills cover common integration work, including sandbox testing.

Apache-2.0 ★ 9 updated 2026-10-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/claude-plugins-community
/plugin install paddle@claude-community
Open on GitHub

What paddle does

The plugin bundles skills for Paddle Billing tasks such as setting up products and prices, adding Checkout to a Next.js app, syncing subscription data through webhooks, and testing in the Paddle sandbox. Describe the work you need, and Claude Code selects a relevant skill. A documentation MCP server gives the assistant access to Paddle materials.

When enabled, Claude Code asks for a sandbox API key and stores it in your keychain. The docs server uses Google or GitHub sign-in; the live server authorizes through browser OAuth. This plugin targets Paddle Billing, so its instructions do not cover Paddle Classic.

What it helps with

  • set up Paddle products and prices
  • add Paddle Checkout to a Next.js app
  • sync subscription data to a database through webhooks
  • test an integration in the Paddle sandbox
  • cancel a subscription at the end of its billing period

Example prompts for the agent

  • Add Paddle Checkout to my Next.js app and handle its events.
  • Check my Paddle webhook and sync subscription updates to the database.

How to install paddle

Plugin marketplace

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

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about paddle

How do I install paddle in Claude Code?

Run these commands in order: /plugin marketplace add anthropics/claude-plugins-community, then /plugin install paddle@claude-community. Claude Code asks for a sandbox API key when you enable the plugin.

What does the paddle plugin do?

It provides skills for common Paddle Billing integrations and connects Claude Code to Paddle documentation. The skills cover checkout, subscriptions, webhooks, and sandbox testing.

Does paddle support Paddle Classic?

No. Its skills are written for Paddle Billing and do not cover Paddle Classic.

Source text

plugin · Apache-2.0
# Paddle agent skills

[Paddle Billing](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills) is the developer-first merchant of record, designed for modern SaaS, AI, mobile app, and digital product businesses. We take care of payments, tax, subscriptions, and metrics with one unified API that does it all.

This repo contains a collection of agent skills that help you implement Paddle in your product. Load them into Claude Code, Codex, Cursor, Gemini CLI, or any agentic coding tool that supports the skills format and your assistant gains step-by-step guidance for the most common Paddle integration tasks.

> **Important:** These skills are written for Paddle Billing. They don't cover Paddle Classic. If you're working with Paddle Classic, see the [Paddle Classic dev docs](https://classic.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills).

## What's included

A batch of skills covering the most common Paddle integration tasks:

- **[`paddle-billing-history`](skills/billing-history/SKILL.md)** — show authenticated customers their past Paddle transactions with invoice download links.
- **[`paddle-catalog-setup`](skills/catalog-setup/SKILL.md)** — create the Paddle products and prices that other skills depend on.
- **[`paddle-checkout-web`](skills/checkout-web/SKILL.md)** — add a Paddle Checkout (overlay or inline) to a Next.js app, with event handling and customer pre-fill.
- **[`paddle-customer-portal`](skills/customer-portal/SKILL.md)** — mint authenticated customer portal sessions so users can self-serve subscriptions, payment methods, and invoices.
- **[`paddle-onboarding`](skills/onboarding/SKILL.md)** — check your account's onboarding status in sandbox or live, see what's missing against the go-live checklist, and fix the gaps the API allows.
- **[`paddle-pricing-pages`](skills/pricing-pages/SKILL.md)** — render country-localized prices using `Paddle.PricePreview()`, with billing frequency toggle and currency formatting.
- **[`paddle-sandbox-testing`](skills/sandbox-testing/SKILL.md)** — exercise the integration end-to-end in the Paddle sandbox: test cards, webhook simulator, local tunnels.
- **[`paddle-subscription-cancel`](skills/subscription-cancel/SKILL.md)** — build a "cancel at end of period" flow with the right ownership checks and webhook reconciliation.
- **[`paddle-subscription-sync`](skills/subscription-sync/SKILL.md)** — mirror Paddle subscription and customer state into your database via webhooks.
- **[`paddle-subscription-update`](skills/subscription-update/SKILL.md)** — upgrade, downgrade, or change subscription items via the API with proration handling.
- **[`paddle-usage-based-billing`](skills/usage-based-billing/SKILL.md)** — add usage-based billing (early access) to a Next.js app: usage balance units, meters, price allowances, usage events, and balance checks.
- **[`paddle-webhooks`](skills/webhooks/SKILL.md)** — receive and verify Paddle webhooks in a Next.js Route Handler, with idempotency and retry handling.

Each skill lives in its own directory under [`skills/`](skills) and ships with a `SKILL.md` containing the skill's frontmatter and instructions. The same skills are mirrored into each provider's plugin folder under [`providers/`](providers) by [`scripts/sync-skills.mjs`](scripts/sync-skills.mjs) — see [CONTRIBUTING.md](CONTRIBUTING.md) for the layout.

## Install as a Claude Code plugin

The Paddle plugin is listed in Anthropic's community plugin marketplace. Inside [Claude Code](https://claude.com/claude-code), run:

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

Then ask Claude something Paddle-shaped, like "help me verify a Paddle webhook in Next.js," and the relevant skill is selected automatically.

When you enable the plugin, Claude Code prompts for your Paddle sandbox API key and stores it securely in your keychain — no shell environment variables needed. The live MCP server authorizes with OAuth in your browser, so it needs no key. (Requires Claude Code v2.1.119 or later.)

To update later, run `/plugin marketplace update claude-community`.

## Install as a Codex plugin

From your terminal, run:

```sh
codex plugin marketplace add PaddleHQ/paddle-agent-skills
```

Then install the `paddle` plugin from the Codex plugin directory.

## Install as a Cursor plugin

Cursor doesn't have a `/plugin install` style command yet, so install via the skills CLI (which adds skill files to your project) and the Cursor MCP deeplinks (which wire up the Paddle MCP servers).

```sh
pnpm dlx skills add https://developer.paddle.com/
```

See the [Cursor setup guide](https://developer.paddle.com/get-started/ai/cursor) for the MCP deeplinks and a Paddle rules file.

## Install as a Gemini CLI extension

From your terminal, run:

```sh
gemini extensions install PaddleHQ/paddle-agent-skills
```

Gemini auto-discovers the bundled [`skills/`](skills) directory at the extension root and wires up the docs and Paddle MCP servers via [`gemini-extension.json`](gemini-extension.json). Export `PADDLE_SANDBOX_API_KEY` for the sandbox server (see [Connect the Paddle MCP servers](#connect-the-paddle-mcp-servers)); the live server authorizes with OAuth.

> **Note:** Since June 18, 2026, Gemini CLI only serves paid Gemini API keys and Gemini Code Assist Standard and Enterprise licenses. Google recommends that everyone else moves to [Antigravity CLI](https://antigravity.google/docs/cli/gcli-migration/). To bring this extension across, install it with Gemini CLI, then run `agy plugin import gemini` to convert it to an Antigravity plugin. Antigravity CLI has an [open issue](https://github.com/google-antigravity/antigravity-cli/issues/25) with OAuth for HTTP MCP servers, so `paddle-docs` and `paddle-live` might not connect there yet.

## Connect the Paddle MCP servers

All of the plugins wire up the same three MCP servers. How you authenticate depends on the environment:

| MCP server       | URL                                  | Authentication                    |
| ---------------- | ------------------------------------ | --------------------------------- |
| `paddle-docs`    | `https://paddlehq.mcp.kapa.ai`       | Google or GitHub sign-in          |
| `paddle-sandbox` | `https://sandbox-mcp.paddle.com/mcp` | Sandbox API key                   |
| `paddle-live`    | `https://mcp.paddle.com/mcp`         | OAuth (authorize in your browser) |

You only need the environments you use. The skills default to sandbox unless you've explicitly opted into live, so the sandbox key is the one to set up first.

`paddle-docs` is hosted by [Kapa.ai](https://kapa.ai) and needs no Paddle credentials. It does ask you to sign in with Google or GitHub the first time you connect, which Kapa uses only for per-user rate limiting and abuse prevention — it requests the `openid` scope from Google and no scopes at all from GitHub. In Codex, start the sign-in with `codex mcp login paddle-docs` (Codex 0.107 or later).

### Sandbox: set an API key

`paddle-sandbox` authenticates with a sandbox API key. Generate one at **Paddle > My account > Settings > Authentication** in the [sandbox dashboard](https://sandbox-vendors.paddle.com/settings/authentication) (keys are prefixed `pdl_sdbx_`), granting the permissions you want the agent to use.

How you supply it depends on the tool:

- **Claude Code** — prompts you for the key when you enable the plugin and stores it in your OS keychain. No shell setup. (See [Install as a Claude Code plugin](#install-as-a-claude-code-plugin).)
- **Codex** and **Gemini CLI** — read the key from the process environment of whatever launches your editor. Set it in your shell profile:

  ```sh
  export PADDLE_SANDBOX_API_KEY=pdl_sdbx_...
  ```

  Restart your editor afterwards so the MCP server picks it up.

- **Cursor** — you paste the key into the install deeplink. (See the [Cursor setup guide](https://developer.paddle.com/get-started/ai/cursor).)

See [`.env.example`](./.env.example) for the full list of variables and inline guidance.

### Live: authorize with OAuth

`paddle-live` authorizes with OAuth, so there's no key to create or store. The first time your agent uses the server, your client opens a browser window to sign in to Paddle and approve access. Depending on the client you may need to trigger this manually — Claude Code and Gemini CLI use `/mcp`, Codex uses `codex mcp login paddle-live`.

An OAuth connection starts with **read** access to what your Paddle user's role permits. To let the agent make changes in live, grant write permissions under **Paddle > Connectors > MCPs**, where you can also review or revoke connections.

If a browser sign-in isn't practical (an automated environment, for example), `paddle-live` also accepts a live API key as a Bearer token. See the [Paddle MCP server docs](https://developer.paddle.com/sdks/ai/paddle-mcp) for that configuration.

### Picking the right MCP at runtime

With both servers connected, the agent sees two parallel toolsets. Be explicit in your prompts about which environment you mean. For example, "create a product in sandbox" routes to `paddle-sandbox`; "create the equivalent product in live" routes to `paddle-live`. Sandbox keys only authenticate against the sandbox URL, so a mismatch surfaces as an auth failure.

## Use the skills outside a plugin

Skills also work in any agentic tool that supports the agent-skills format. Use the [`skills` CLI](https://github.com/vercel-labs/skills) to add them to your project:

```sh
pnpm dlx skills add https://developer.paddle.com/
```

You can also add skills manually by copying the contents of a skill's directory into your project's `.agents/skills/` directory, or a global `~/.agents/skills/` directory to share across projects.

## Contributing

Found a bug or want to suggest an improvement? See [CONTRIBUTING.md](CONTRIBUTING.md) and open an issue.

## Get help

For help with your Paddle integration, contact our support team at [[email protected]](mailto:[email protected]).

For feedback about Paddle's developer experience or these skills specifically, contact the Paddle DX team at [[email protected]](mailto:[email protected]).

## Learn more

- [Paddle developer docs](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills)
- [Paddle agent skills](https://developer.paddle.com/sdks/ai/agent-skills?utm_source=dx&utm_medium=paddle-agent-skills)
- [Paddle docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp?utm_source=dx&utm_medium=paddle-agent-skills)
- [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp?utm_source=dx&utm_medium=paddle-agent-skills)
- [Sign up for Paddle Billing](https://login.paddle.com/signup?utm_source=dx&utm_medium=paddle-agent-skills)

© PaddleHQ · Apache-2.0 · PaddleHQ/paddle-agent-skills

Similar plugins

All plugins for Writing and docs →

Project sponsors

Companies that keep this analytics open