Connect Paddle Billing

Paddle sends payment and refund updates to Referral Bear. Your affiliate’s referral ID links the checkout to their account.

Connect your account

Sign in as the program owner, then open Integrations and find Paddle Billing.

1. In Paddle, open Developer Tools → Authentication. Create an API key with read access to Customers, Transactions, Subscriptions, and Adjustments.
2. In Referral Bear, choose Live or Sandbox under Environment. Paste the matching Paddle API key.
3. Choose Copy address beside Webhook address.
4. In Paddle, open Developer Tools → Notifications → New destination. Choose Webhook, then paste the address.
5. Select subscription.created, subscription.canceled, transaction.completed, adjustment.created, and adjustment.updated. Save the destination.
6. Copy its secret into Webhook secret in Referral Bear.
7. Choose Save Paddle settings. The connection should show the environment you chose.

Use the key and secret from the same Paddle environment. Only the owner can change this connection. Managers can read events and retry them.

Add referrals to checkout

First, follow Turn tracking on and Add the browser script in Install website tracking. Return here for checkout; the Stripe customer step does not apply to Paddle.

Pass the saved click ID in Paddle’s customData when you open checkout:

await window.referralBear.ready;
const referral = window.referralBear.getReferral();
 
Paddle.Checkout.open({
  items: [{ priceId: "YOUR_PADDLE_PRICE_ID", quantity: 1 }],
  ...(referral?.click_id
    ? { customData: { referralbear_referral: referral.click_id } }
    : {}),
});

Set up Paddle.js  before running this code. Keep your API key on the server. Paddle.js uses a client-side token.

Use the same currency for the Paddle checkout and your Referral Bear program. A payment in another currency stops for review.

Referral Bear checks the saved referral and the customer returned by Paddle. The affiliate must be active, and the link must have been valid when checkout started. If the customer already has a different affiliate or payment connection, the event stops for review.

Check a payment

1. Open an affiliate’s referral link and complete a Paddle checkout.
2. Open Integrations → Paddle Billing and choose Refresh.
3. Find transaction.completed under Paddle events. Its status should become processed.
4. Open Transactions to find the payment.
5. Open Commissions to check the reward. Your commission rules decide whether the payment earns one.

Paddle’s API supplies the payment amount. Repeated delivery of the same payment does not create another payment or commission.

Refunds and trials

Approved refunds reduce the related commission. A partial refund reduces part of it; a full refund reverses it. A refund received before its payment is kept until the payment arrives. Refunds do not change a paid commission back to unpaid.

A trial signup can earn a signup reward when a rule matches. If the trial event arrives after payment, Referral Bear checks the original trial and payment dates. It also checks that the affiliate’s link was valid when the trial began. The signup reward is added once.

Fix an event

Use Load more events to read older events. If a rule needs payment history, missing payments or refunds must be resolved before it can award a commission. Credits, chargebacks, and reversed adjustments require review.