Imported from terminalskills/skills (skills/paddle/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill paddle. Copyright stays with the author (Apache-2.0).

Paddle

Overview

Paddle is a merchant of record — it handles payments, tax compliance (VAT, sales tax), invoicing, and fraud protection. Unlike Stripe, you don't need to register for tax in every country. Paddle sells on your behalf and remits taxes globally.

Instructions

Step 1: Checkout Integration

// components/Checkout.tsx — Paddle.js overlay checkout
declare global { interface Window { Paddle: any } }

export function PricingButton({ priceId }: { priceId: string }) {
  const handleCheckout = () => {
    window.Paddle.Checkout.open({
      items: [{ priceId, quantity: 1 }],
      customer: { email: 'user@example.com' },
      customData: { userId: 'usr_123' },
    })
  }

  return <button onClick={handleCheckout}>Subscribe</button>
}

// Add to layout:
// <script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
// Paddle.Initialize({ token: 'live_xxx' })

Step 2: Webhook Handler

// api/paddle/webhook.ts — Process Paddle events
import { Paddle } from '@paddle/paddle-node-sdk'

const paddle = new Paddle(process.env.PADDLE_API_KEY!)

export async function POST(req: Request) {
  const body = await req.text()
  const signature = req.headers.get('paddle-signature')!

  const event = paddle.webhooks.unmarshal(body, process.env.PADDLE_WEBHOOK_SECRET!, signature)

  switch (event.eventType) {
    case 'subscription.created':
      await db.user.update({
        where: { paddleCustomerId: event.data.customerId },
        data: { plan: 'pro', subscriptionId: event.data.id },
      })
      break
    case 'subscription.canceled':
      await db.user.update({
        where: { subscriptionId: event.data.id },
        data: { plan: 'free', canceledAt: new Date() },
      })
      break
    case 'transaction.completed':
      // Payment received — update invoice records
      break
  }

  return new Response('OK')
}

Step 3: API Usage

// lib/paddle.ts — Manage subscriptions server-side
import { Paddle } from '@paddle/paddle-node-sdk'
const paddle = new Paddle(process.env.PADDLE_API_KEY!)

// Create a customer
const customer = await paddle.customers.create({
  email: 'user@example.com',
  name: 'John Doe',
})

// List subscriptions
const subscriptions = await paddle.subscriptions.list({
  customerId: [customer.id],
})

// Cancel subscription
await paddle.subscriptions.cancel(subscriptionId, {
  effectiveFrom: 'next_billing_period',
})

Guidelines

• Paddle is a merchant of record — it handles VAT, sales tax, invoices. You receive net payouts.
• Paddle takes ~5% + payment processing fees. Higher than Stripe, but includes tax compliance.
• Use Paddle Billing for subscriptions, Paddle Checkout for one-time purchases.
• Best for indie devs and small teams who don't want to deal with global tax registration.