Paddle Integration

Automatically track revenue from Paddle and attribute it to the visitors who converted.

Overview

The Paddle integration connects your Paddle account to Ripples so you can:

• See revenue attributed to each visitor and their acquisition source
• Track transactions, subscriptions, and adjustments automatically
• Backfill historical payment data when you first connect
• Handle refunds and credits (negative revenue events are created automatically)

Revenue events appear in the visitor timeline and contribute to each profile's lifetime revenue total.

Prerequisites

Before connecting Paddle, make sure you have:

1. Persist mode enabled — Ripples uses a cookie (_rpl_vid) to track visitors across sessions. This is the default behavior.
2. User identification — Call ripples.identify() when users sign in so we can match Paddle transactions to visitor profiles by email.

// Call this after login / signup
ripples.identify({
  id: "user_123",
  email: "[email protected]",
  name: "Jane Doe",
  plan: "pro",
})

Create an API Key

1. Go to your Paddle Dashboard → Developer Tools → Authentication
2. Click "Generate API key"
3. Give it a name like Ripples Analytics
4. Set the following permissions:

The Notification settings: Read & Write permission allows Ripples to automatically create a webhook notification destination in your Paddle account to receive payment events in real-time.

5. Click "Generate" and copy the key (it starts with pdl_)

Connect in Settings

1. Open your project dashboard in Ripples
2. Click the Integrations link in the header
3. Find the Paddle card and click Connect
4. Paste your API key and click Connect

Once connected, Ripples will:

• Create a notification destination in your Paddle account automatically
• Begin importing your historical transactions (backfill)
• Start receiving new payment events in real-time

Revenue Attribution

Ripples uses a 3-tier fallback to attribute each Paddle payment to a visitor:

Tier 1: Custom Data (Best)

Pass the visitor ID in the custom_data field when creating a Paddle checkout or transaction. This gives the most accurate attribution because it directly links the payment to the browsing session.

// Paddle.js (Client-side)
const visitorId = ripples.getVisitorId()

Paddle.Checkout.open({
  items: [{ priceId: "pri_..." }],
  customData: { ripples_visitor_id: visitorId },
})

// Next.js / Node.js (Server-side)
import { cookies } from "next/headers"

export async function createCheckout() {
  const cookieStore = await cookies()
  const visitorId = cookieStore.get("_rpl_vid")?.value

  // Pass to Paddle API when creating a transaction
  const transaction = await paddle.transactions.create({
    items: [{ priceId: "pri_...", quantity: 1 }],
    customData: { ripples_visitor_id: visitorId },
  })
}

// Laravel (Server-side)
$visitorId = $request->cookie('_rpl_vid');
// or from frontend: $request->input('visitorId')

// Pass to Paddle API when creating a transaction
$paddle->transactions->create([
    'items' => [['price_id' => 'pri_...', 'quantity' => 1]],
    'custom_data' => ['ripples_visitor_id' => $visitorId],
]);

Tier 2: Email Matching (Automatic)

If Tier 1 custom data is not present, Ripples matches the Paddle customer email to a visitor profile. This works when you have called ripples.identify() with the user's email.

No extra setup needed — this happens automatically.

Tier 3: Customer ID (Returning Customers)

For subsequent payments, Ripples remembers the Paddle customer ID from previous attributions. If a customer was attributed once (via Tier 1 or 2), all future payments from that customer are automatically attributed to the same visitor.

Events Tracked

The following Paddle events are processed:

Historical Backfill

When you first connect Paddle, Ripples automatically imports all your historical completed transactions and attributes them using the same 3-tier fallback. Active subscriptions are also synced to update visitor plan fields.

You can check the backfill status on the Integrations settings page. If needed, use the Re-sync button to clear and re-import all data.

Deduplication

Ripples automatically prevents duplicate revenue events:

• Each Paddle transaction and adjustment is tracked by its unique ID
• Webhook retries and backfill re-runs are automatically deduplicated
• If you use the Paddle integration, you do not need to send revenue events from the frontend SDK — Paddle handles it automatically

Sandbox Support

Ripples automatically detects Paddle sandbox API keys (containing test_ or sandbox in the key) and routes requests to the Paddle sandbox environment. You can test the full integration flow without processing real payments.

Disconnecting

To disconnect the integration, go to Integrations settings and click Disconnect on the Paddle card. You can choose to keep or remove the imported revenue data. The notification destination in your Paddle account will be automatically removed.