Referrals with Paddle Billing

Connect Paddle Billing and every paid transaction, renewal, refund and chargeback reaches the program, credited to the partner whose link or code brought the customer. Paddle signs each delivery with a secret of its own, with a timestamp, so a delivery cannot be replayed later.

Add a notification destination

1. Open the program, Setup, Billing, Paddle, and copy the endpoint URL.

2. In Paddle: Developer Tools, Notifications, New destination. Paste the URL and select these events:

   transaction.completed, adjustment.created, adjustment.updated, discount.created, discount.updated

3. Open the destination again with Edit destination: Paddle shows its secret key (it starts pdl_ntfset_). Paste it on the card.

Pass the referral to checkout

Give Paddle.js the code as custom data. Paddle stores it on the transaction, copies it to the subscription, and from there to every renewal, so renewals are credited too.

Paddle.Checkout.open({
  items: [{ priceId: "pri_monthly", quantity: 1 }],
  customData: { boltclaw_ref: BoltClawReferral.code(), boltclaw_customer_id: "acme-user-10442" },
});

Without boltclaw_customer_id, Paddle's own customer id (ctm_) stands in. When a transaction's line items add up to what was paid, each one is read, so a reward rule for one product or price applies to it.

Refunds and chargebacks

Paddle reports both as adjustments. A refund counts once Paddle approves it (most start as pending approval), for its own amount, so a partial refund takes back that share of the commission. A chargeback reverses the sale in full.

Discount codes

Paddle sends a discount as an id. With discount.created and .updated selected, Bolt Claw learns each id's code, so a sale made with a partner's code alone is credited to them.

Test mode

Paddle's sandbox is its own account, and its events do not say they are tests. Add a second Paddle integration for the sandbox and switch Sandbox on: every event it receives is test data.

Check it works

On the program's Setup tab, the Billing row of the setup status turns Connected with the first verified event, and says when a delivery was refused (nearly always the wrong secret). Then press Send a test sale to see a click, a signup, a sale and a refund go through your rules with test data, or make a real test purchase in your Paddle sandbox. See Connect your billing system for the whole setup status and what test data never does.