Get started with Paddle in Node.js

This quickstart walks through installing the Paddle Node.js SDK, initializing a client, making your first read-only API call, and verifying webhook signatures. By the end, you'll have a working sandbox client and webhook handler.

Before you begin

You'll need:

• A Paddle sandbox account.
• A sandbox API key with permission to read and write products.
• Node.js 20 or later.

Install the SDK

Install @paddle/paddle-node-sdk using your package manager.

npm install @paddle/paddle-node-sdk

pnpm add @paddle/paddle-node-sdk

yarn add @paddle/paddle-node-sdk

bun add @paddle/paddle-node-sdk

Initialize the client

Import the SDK and create a Paddle client. Pass your API key directly, and set the environment to sandbox while you're building.

import { Environment, LogLevel, Paddle } from '@paddle/paddle-node-sdk'

const paddle = new Paddle(process.env.PADDLE_API_KEY!, {
  environment: Environment.sandbox,
  logLevel: LogLevel.verbose,
})

For production, drop the environment option (or set it to Environment.production) and lower logLevel to LogLevel.error:

const paddle = new Paddle(process.env.PADDLE_API_KEY!)

Make your first request

List products to confirm the client is wired up. The SDK returns a ProductCollection that paginates lazily. Call .next() to fetch the first page.

import { Paddle, Product, ProductCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle(process.env.PADDLE_API_KEY!)

async function listProducts() {
  const productCollection: ProductCollection = paddle.products.list()
  const firstPage: Product[] = await productCollection.next()
  console.log('First page of products:', firstPage)
}

listProducts()

If your sandbox account is new, the array is empty. Create a product in the dashboard or via paddle.products.create() to see results.

Verify webhooks

You can use webhooks to keep your app in sync with Paddle. For example, you can provision access when a subscription is created, or revoke access when a subscription is cancelled.

The SDK exposes a paddle.webhooks.unmarshal() helper that verifies the signature and parses the event in one call. Always verify the signature before acting on the payload.

import { Paddle, EventName } from '@paddle/paddle-node-sdk'
import express, { Request, Response } from 'express'

const paddle = new Paddle(process.env.PADDLE_API_KEY!)
const app = express()

app.post(
  '/webhooks',
  express.raw({ type: 'application/json' }),
  async (req: Request, res: Response) => {
    const signature = (req.headers['paddle-signature'] as string) || ''
    const rawRequestBody = req.body.toString()
    const secretKey = process.env.PADDLE_WEBHOOK_SECRET!

    try {
      const eventData = await paddle.webhooks.unmarshal(
        rawRequestBody,
        secretKey,
        signature,
      )
      switch (eventData.eventType) {
        case EventName.TransactionCompleted:
          // Provision access, send a receipt, etc.
          break
        case EventName.SubscriptionUpdated:
          // Sync the subscription to your database.
          break
      }
      res.status(200).send('ok')
    } catch (err) {
      res.status(400).send('invalid signature')
    }
  },
)

app.listen(3000)

Use express.raw() middleware on the webhook route. unmarshal needs the raw request body string to verify the signature. For the full webhook setup flow, see Verify webhook signatures.

Next steps

• Fork the Next.js SaaS starter kit and deploy it to Vercel.
• Use the webhook simulator to test webhook events.
• Browse the API reference to see every endpoint Paddle exposes.
• View the Node.js SDK reference for the full SDK reference.