> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prelaunch.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Paddle Integration

> Process payments and manage subscriptions with Paddle

## Paddle Integration Overview

PreLaunch comes with built-in integration for the [Paddle](https://paddle.com/) 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.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/maplegroup/images/paddle-demo.png" alt="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](https://www.paddle.com/) 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](https://vendors.paddle.com/authentication)
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:

```typescript theme={null}
// 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:

```tsx theme={null}
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:

```tsx theme={null}
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](https://github.com/MapleShaw/prelaunch/blob/main/PADDLE-WEBHOOK-SETUP.md) file.

## Customer Account Management

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

```tsx theme={null}
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](https://ngrok.com/) to create a temporary public URL for testing webhooks

## Troubleshooting

<AccordionGroup>
  <Accordion title="Checkout button not displaying or not working">
    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
  </Accordion>

  <Accordion title="Webhook not receiving events">
    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
  </Accordion>

  <Accordion title="Subscription status not updating">
    Confirm the following:

    * Is the webhook correctly set up and receiving events?
    * Is the database connection working?
    * Check server logs for errors
  </Accordion>
</AccordionGroup>

## 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

## Related Links

<CardGroup cols={2}>
  <Card title="Paddle Official Documentation" icon="book" href="https://developer.paddle.com/">
    Learn more about the Paddle API
  </Card>

  <Card title="Pricing Feature" icon="money-bill" href="/features/payments">
    Learn about PreLaunch's pricing page configuration
  </Card>
</CardGroup>