PaddleJS and Webhook Events Cheat Sheet

This quick reference guide summarizes the most common patterns and configurations in Paddle.

1. Client-Side Paddle.js Initialization

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  environment: "sandbox", // Use "production" for live stores
  token: "pt_test_your-public-client-token",
});

2. Launching Checkout Overlay

paddle.Checkout.open({
  items: [
    {
      priceId: "pri_01hsabcd12345",
      quantity: 1,
    },
  ],
  customData: {
    userId: "user-12345",
  },
  settings: {
    theme: "light",
    allowRecovery: true,
  },
});

3. Node.js Backend SDK Setup

import { Paddle } from "@paddle/paddle-node-sdk";

const paddle = new Paddle({
  apiKey: "paddlesd_test_secret-key-token",
  environment: "sandbox",
});

4. Key Webhook Event Payloads

{
  "event_id": "evt_01hsabc...",
  "event_type": "subscription.created",
  "occurred_at": "2026-06-16T20:00:00Z",
  "data": {
    "id": "sub_01hsabc...",
    "customer_id": "ct_01hsabc...",
    "status": "active",
    "custom_data": {
      "userId": "user-12345"
    },
    "items": [
      {
        "price_id": "pri_01hsabc...",
        "quantity": 1
      }
    ]
  }
}

5. Test Billing Zip/Postal Code Mapping

• US: 90210
• CA: M4B 1B3
• UK: W1A 1AA
• DE: 10115