Paddle Integration

Paddle Integration Overview

PreLaunch comes with built-in integration for the Paddle payment system, allowing you to easily process payments and manage user subscriptions. Paddle offers a powerful billing system with support for global payments and subscription management. Paddle Integration Example

Features

Support for one-time payments and subscription plans
Built-in checkout flow
Sandbox testing environment
Webhook integration for automatic subscription status updates
Customer account management
Support for multiple currencies

Prerequisites

Before using the Paddle integration, you need to:

Create a Paddle account
Create products and pricing plans in the Paddle dashboard
Obtain API keys and client tokens

Environment Setup

Set Environment Variables

Add the following environment variables to your .env.local file:

# Paddle Configuration
PADDLE_SANDBOX=true                               # Use sandbox mode for development
PADDLE_API_KEY=your-api-key-here                  # Paddle API key
PADDLE_NOTIFICATION_WEBHOOK_SECRET=your-webhook-secret-here  # Webhook secret
NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=your-paddle-client-token-here # Paddle client token

Get Paddle Credentials

Log in to your Paddle Dashboard
Navigate to Developer Tools > Authentication
Copy your API Key
Get your Client Token - create one in Developer Tools > Clients

Product Configuration

Set Up Products in Paddle

Navigate to Catalog > Products in the Paddle dashboard
Click Create Product
Fill in the product details and save
Create product prices (at least one price per product)
Note down the product ID and price ID

Update PreLaunch Configuration

In the config.ts file, update the configuration using the product and price IDs you created in Paddle:

// config.ts
paddle: {
  plans: [
    {
      priceId: "pri_xxxxxxxxxxxxxxxx",  // Price ID, starts with pri_
      isFeatured: true,
      icon: "/assets/icons/paddle-icon.svg",
      name: "Basic Plan",
      description: "Ideal for individuals and small teams",
      price: 99,
      priceAnchor: 149,  // Original price (for displaying discounts)
      features: [
        "Complete landing page template",
        "SEO optimization",
        "Waitlist functionality",
        "High performance loading",
        // Other features...
      ],
    },
    // More pricing plans...
  ],
}

Using Paddle Checkout

PreLaunch provides two ways to use Paddle checkout:

1. Using the Pre-built Checkout Button

The simplest method is to use the built-in ButtonCheckout component:

import { ButtonCheckout } from '@/components/ButtonCheckout';

export default function PricingSection() {
  return (
    <div className="pricing-card">
      <h3>Basic Plan</h3>
      <p>Ideal for individuals and small teams</p>
      <p className="price">$99</p>
      
      {/* Paddle checkout button */}
      <ButtonCheckout priceId="pri_xxxxxxxxxxxxxxxx" />
    </div>
  );
}

2. Using the Paddle.js API

If you need more customization options, you can directly use the Paddle.js API:

import { usePaddle } from '@/hooks/usePaddle';

export default function CustomCheckout() {
  const { checkout } = usePaddle();
  
  const handleCheckout = () => {
    checkout({
      priceId: 'pri_xxxxxxxxxxxxxxxx',
      quantity: 1,
      customerEmail: 'user@example.com', // Optional
      successUrl: 'https://yourdomain.com/thank-you', // Optional
      // Other options...
    });
  };
  
  return (
    <button onClick={handleCheckout}>
      Buy Now
    </button>
  );
}

Webhook Setup

To handle Paddle events (such as successful payments, subscription status changes, etc.), you need to set up a webhook:

Navigate to Developer Tools > Webhooks in the Paddle dashboard
Create a new webhook endpoint with the URL: https://yourdomain.com/api/paddle/webhook
Select the events you want to receive (at minimum: subscription.activated, subscription.cancelled, payment.succeeded)
Copy the generated webhook secret to your .env.local file: PADDLE_NOTIFICATION_WEBHOOK_SECRET

For detailed setup instructions, please refer to the PADDLE-WEBHOOK-SETUP.md file.

Customer Account Management

PreLaunch includes a customer account management component that allows users to view and manage their subscriptions:

import { ButtonPaddleAccount } from '@/components/ButtonPaddleAccount';

export default function AccountPage() {
  return (
    <div className="account-page">
      <h1>Your Account</h1>
      
      {/* Paddle customer account management */}
      <ButtonPaddleAccount />
    </div>
  );
}

Local Development Notes

In your local development environment:

Set PADDLE_SANDBOX=true in your .env.local file
Use product and price IDs created in the Paddle sandbox environment
Note that webhooks need a publicly accessible URL; you can use tools like ngrok to create a temporary public URL for testing webhooks

Troubleshooting

Checkout button not displaying or not working

Webhook not receiving events

Subscription status not updating

Production Deployment

When you’re ready to deploy to production:

Create production environment products and pricing plans in Paddle
Update environment variables, set PADDLE_SANDBOX=false
Use production environment API keys and client tokens
Update the webhook URL to point to your production domain

Paddle Official Documentation

Learn more about the Paddle API

Pricing Feature

Learn about PreLaunch’s pricing page configuration

Get Started

Core Features

Customization