Paddle

Paddle agent skills

Paddle Billing 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.

What's included

Ten skills covering the most common Paddle integration tasks:

• paddle-billing-history — show authenticated customers their past Paddle transactions with invoice download links.
• paddle-catalog-setup — create the Paddle products and prices that other skills depend on.
• paddle-checkout-web — add a Paddle Checkout (overlay or inline) to a Next.js app, with event handling and customer pre-fill.
• paddle-customer-portal — mint authenticated customer portal sessions so users can self-serve subscriptions, payment methods, and invoices.
• paddle-pricing-pages — render country-localized prices using Paddle.PricePreview(), with billing frequency toggle and currency formatting.
• paddle-sandbox-testing — exercise the integration end-to-end in the Paddle sandbox: test cards, webhook simulator, local tunnels.
• paddle-subscription-cancel — build a "cancel at end of period" flow with the right ownership checks and webhook reconciliation.
• paddle-subscription-sync — mirror Paddle subscription and customer state into your database via webhooks.
• paddle-subscription-update — upgrade, downgrade, or change subscription items via the API with proration handling.
• paddle-webhooks — 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/ 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/ by scripts/sync-skills.mjs — see CONTRIBUTING.md for the layout.

Install as a Claude Code plugin

Inside Claude Code, run:

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

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

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

Install as a Codex plugin

From your terminal, run:

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

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

See the Cursor setup guide for the MCP deeplinks and a Paddle rules file.

Install as a Gemini CLI extension

From your terminal, run:

gemini extensions install PaddleHQ/paddle-agent-skills

Gemini auto-discovers the bundled skills/ directory at the extension root and wires up the docs and Paddle MCP servers via gemini-extension.json. No extra setup needed.

Connect the Paddle MCP servers

All of the plugins wire up the same three MCP servers. They share configuration through environment variables, so set the keys once and any of the four agents can use them.

MCP server	URL	API key env var
paddle-docs	https://paddlehq.mcp.kapa.ai	(no key required)
paddle-sandbox	https://sandbox-mcp.paddle.com/mcp	PADDLE_SANDBOX_API_KEY
paddle-live	https://mcp.paddle.com/mcp	PADDLE_LIVE_API_KEY

You only need to set the keys for the environments you use. The unset one will fail to authenticate at editor startup and the agent logs the failure but otherwise carries on. The skills default to sandbox unless you've explicitly opted into live, so PADDLE_SANDBOX_API_KEY is the one to start with during development.

1. Get a Paddle API key

Generate keys at Paddle > Developer tools > Authentication:

• Sandbox: sandbox dashboard (keys prefixed pdl_sdbx_)
• Live: live dashboard

Grant the permissions you want the agent to use.

2. Export the keys in your shell

The plugins and the Gemini extension read the keys from the process environment of whatever launches your editor. Set them in your shell profile:

export PADDLE_SANDBOX_API_KEY=pdl_sdbx_...
export PADDLE_LIVE_API_KEY=...  # only if you also want the live MCP

See .env.example for the full list of variables and inline guidance.

Restart your editor after setting the variables so the MCP servers pick them up.

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 and live keys only against the live 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 to add them to your project:

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 .agent/skills/ directory, or a global ~/.agent/skills/ directory to share across projects.

Contributing

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

Get help

For help with your Paddle integration, contact our support team at sellers@paddle.com.

For feedback about Paddle's developer experience or these skills specifically, contact the Paddle DX team at team-dx@paddle.com.

Learn more

• Paddle developer docs
• Paddle agent skills
• Paddle docs MCP server
• Paddle MCP server
• Sign up for Paddle Billing