Skip to main content

​
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:
  1. Create a Paddle account
  2. Create products and pricing plans in the Paddle dashboard
  3. 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

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

​
Product Configuration

​
Set Up Products in Paddle

  1. Navigate to Catalog > Products in the Paddle dashboard
  2. Click Create Product
  3. Fill in the product details and save
  4. Create product prices (at least one price per product)
  5. 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:
  1. Navigate to Developer Tools > Webhooks in the Paddle dashboard
  2. Create a new webhook endpoint with the URL: https://yourdomain.com/api/paddle/webhook
  3. Select the events you want to receive (at minimum: subscription.activated, subscription.cancelled, payment.succeeded)
  4. 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:
  1. Set PADDLE_SANDBOX=true in your .env.local file
  2. Use product and price IDs created in the Paddle sandbox environment
  3. Note that webhooks need a publicly accessible URL; you can use tools like ngrok to create a temporary public URL for testing webhooks

​
Troubleshooting

Check the following:
  • Ensure the NEXT_PUBLIC_PADDLE_CLIENT_TOKEN environment variable is correctly set
  • The price ID format should be pri_xxxxxx
  • Open the browser console to check for Paddle-related errors
Check the following:
  • Is the webhook URL publicly accessible?
  • Is PADDLE_NOTIFICATION_WEBHOOK_SECRET correctly set?
  • Check the webhook logs in the Paddle dashboard for failure records
Confirm the following:
  • Is the webhook correctly set up and receiving events?
  • Is the database connection working?
  • Check server logs for errors

​
Production Deployment

When you’re ready to deploy to production:
  1. Create production environment products and pricing plans in Paddle
  2. Update environment variables, set PADDLE_SANDBOX=false
  3. Use production environment API keys and client tokens
  4. 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
⌘I