Connect Paddle

Paddle Billing transactions land in Statiz in real time through a notification destination you create in your own Paddle dashboard, refunds net out automatically, and Sync now backfills up to a year of history. Paddle names its webhooks “notification destinations” — same thing, one extra word.

Connect at most ONE revenue source per website — either the Paddle integration or the client-side statiz.revenue() beacon, never both, or the same payment counts twice (why).

Step 1: Create the destination

In the Paddle dashboard, open Developer Tools → Notifications (vendors.paddle.com/notifications) and click New destination.

Paddle's documentation for creating and updating notification destinations.
Paddle's notification-destination guide — Developer Tools → Notifications → New destination.
  1. Choose Webhook as the destination type and paste the URL shown in Statiz under Settings → Revenue → Connect Paddle — it looks like https://your-statiz-url/api/webhooks/paddle/{your site id}. Statiz must be reachable at a public URL (localhost can't receive webhooks — deploy first or use a tunnel).
  2. Select exactly these four events:
    • transaction.paid and transaction.completed — money received / a terminal success (positive revenue rows)
    • adjustment.created and adjustment.updated — refunds (a negative row once the adjustment is approved; pending ones are ignored until they are)
  3. After creating the destination, copy its endpoint secret (pdl_ntfset_…) — you'll paste it in Step 3.

Step 2: Copy your API key

In the Paddle dashboard, open Developer tools → API Keys and copy an API key. Read access to Transactions, Adjustments and Products is enough — webhooks are created by you, not by Statiz.

  • pdl_live_apikey_… — production key (live keys only — sandbox keys are not accepted)

If your key doesn't start with this prefix it's a legacy key — create a new one (Paddle is revoking legacy keys).

Step 3: Connect in Statiz

Open your website in Statiz, go to Settings → Revenue, pick Paddle as the provider, then paste the API key and the pdl_ntfset_… endpoint secret and click Connect.

Statiz's Settings → Revenue tab with Paddle selected, showing the webhook setup guide with the endpoint URL, the four events, and the API key plus signing secret fields.
Settings → Revenue with Paddle selected — the guide lists all four events for the destination.

Statiz verifies the key with a one-item transaction list (which also proves the key matches its environment), encrypts both values with AES-256-GCM, and stores them. The card then shows your first product's name as the account label.

Step 4: Sync and verify

Click Sync now once connected. The first sync backfills transactions and approved refund adjustments from Paddle's API — up to 365 days — and reports how many were imported. Later transactions arrive in real time through the destination.

The connected Paddle card in Statiz showing the product label, the webhook URL, and the Sync now button with an import result.
Connected — the card shows the URL your Paddle destination must point at.

To verify the webhook end-to-end, complete a checkout and watch the Revenue tile on the dashboard jump. Duplicate deliveries and re-syncs are harmless — rows key on the txn_… and adj_… ids, so nothing is counted twice.

Notes & caveats

  • Paddle revenue counts totals.total — the charged total after discount and tax.
  • Refunds land only when the adjustment is approved — pending or rejected adjustments are not money and are skipped.
  • To attribute payments to tracked visitors, pass statz_visitor_id in the transaction's custom_data (set it on the checkout) — the full recipe is in Link payments to visitors.
  • Paddle retries failed deliveries; Statiz acknowledges everything it processed, so retries are always safe.
  • Disconnecting removes the stored key and secret — also delete the destination in Paddle's dashboard if you're done.