paddle-checkout-web

Build a Paddle Checkout in Next.js

When to use this skill

Use this skill when adding a hosted Paddle checkout to a Next.js (App Router) app, either as an overlay (modal-style) or inline (embedded within your page). It covers initialization, opening checkout with line items, listening to events, customer pre-fill, the post-checkout redirect, and the throttled updateItems pattern for cart-like UIs.

This skill is client-side only. Pair it with:

• webhooks to receive transaction.completed / subscription.created events on your server.
• subscription-sync to mirror Paddle subscription state into your database.
• sandbox-testing to test the integration end-to-end in the Paddle sandbox.

Prerequisites

You need:

• A Paddle account, with the sandbox environment active during development.
  • Sign up for sandbox: https://sandbox-vendors.paddle.com/
  • Sign up for live: https://vendors.paddle.com/
• At least one product and price set up. Use catalog-setup if you haven't yet — note the price ID (looks like pri_01h...) for use below.
• Your domain approved for checkout under Paddle > Checkout > Website approval. Domains are approved automatically in sandbox.
• Your default payment link set under Paddle > Checkout > Checkout settings > Default payment link. You can use https://localhost/ for sandbox, then change later.
• Two environment variables from Paddle > Developer tools > Authentication:

NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=test_...   # client-side token, safe to expose
NEXT_PUBLIC_PADDLE_ENV=sandbox             # or "production"

If a Paddle MCP server is available to you, call client.clientTokens.create({ name: "Frontend dev token" }) inside an execute to provision the token programmatically rather than asking the user to copy it from the dashboard. Note clientTokens is camelCase.

The Paddle MCP exposes three tools per server (search, execute, report_missing_tool). Workflow: call search to confirm the exact method name and parameter shapes, then call execute with an async function that calls client.<resource>.<operation>(...). Method paths are camelCase (client.clientTokens.create, client.pricingPreview.preview). Body params and response fields are snake_case (tax_category, product_id, unit_price, currency_code). Pagination is { pagination: { hasMore }, data: [...] } with { after: "<last_id>" } — not .next() / .hasMore. Chain multi-step workflows inside one execute; variables don't persist between calls. Hard caps: 50 API calls per execute, 30s timeout, 32KB code.