You are helping integrate LinkJolt affiliate tracking into a web application using Paddle Billing.

## Context
- Merchant ID: YOUR_MERCHANT_ID
- Platform: Paddle Billing (not Paddle Classic)
- Webhook Endpoint: https://www.linkjolt.io/api/webhooks/paddle?merchant=YOUR_MERCHANT_ID
- Tracking Script: https://www.linkjolt.io/api/tracking.js?id=YOUR_MERCHANT_ID

## Connecting Paddle (the merchant does this in LinkJolt)
The quickest route: LinkJolt → Integration Hub → Paddle → Step 1, paste a Paddle API key made in Paddle under Developer tools → Authentication → API keys, with permission to write notification settings. LinkJolt creates a notification destination called LinkJolt that sends the events below to `https://www.linkjolt.io/api/webhooks/paddle?merchant=YOUR_MERCHANT_ID`, saves its secret key, and does not keep the API key. A sandbox API key connects the sandbox account the same way; its sales record as test data and never become payable commissions.

## Or by hand (in the Paddle dashboard, the merchant does these)
1. Paddle dashboard → Developer tools → Notifications → New destination.
2. Choose URL and paste this address exactly: `https://www.linkjolt.io/api/webhooks/paddle?merchant=YOUR_MERCHANT_ID`. The `merchant` parameter is how LinkJolt finds this brand's secret, so keep it. Set the usage type to Platform, so Paddle sends real events only, never simulated ones.
3. Select exactly these events. Nothing else is needed:
   - `transaction.completed`: sales, renewals and paid invoices
   - `adjustment.created`: credits and chargebacks
   - `adjustment.updated`: refunds, once Paddle approves them
   Renewals arrive as `transaction.completed`. Paddle Billing has no `subscription.payment_succeeded` event (that was Paddle Classic).
4. Save the destination, then copy its secret key (it starts with `pdl_ntfset_`).
5. Paste it in LinkJolt → Integration Hub → Paddle → Step 1, under "Set it up by hand instead".
6. Testing with a Paddle sandbox account by hand? Repeat steps 1 to 4 in the sandbox dashboard and save that destination's secret in LinkJolt → Settings → Payment Providers with provider "Paddle sandbox". Sandbox sales record as test data and never become payable commissions.

---

## Code Integration

### Add Tracking Script

Add this to your website's `<head>` tag:

**HTML:**
```html
<script src="https://www.linkjolt.io/api/tracking.js?id=YOUR_MERCHANT_ID" async></script>
```

**Next.js / React:**
```tsx
import Script from 'next/script'

// Add this in your layout.tsx or _app.tsx
<Script
  src="https://www.linkjolt.io/api/tracking.js?id=YOUR_MERCHANT_ID"
  strategy="afterInteractive"
/>
```

### Pass tracking to Paddle Checkout

Use `customData` (camelCase) on `Paddle.Checkout.open()`. Our webhook handler reads the tracking out of `custom_data.linkjolt`:

```typescript
Paddle.Checkout.open({
  items: [{ priceId: 'pri_xxx', quantity: 1 }],
  customData: {
    linkjolt: window.linkjolt?.referral || '',
  },
});
```

**Important**: use `customData`, NOT `passthrough` (passthrough is Paddle Classic). The field name `linkjolt` is what our handler extracts, so don't rename it.

No access to the checkout code? Register the affiliate's Paddle discount in LinkJolt instead (a coupon with provider Paddle and its `dsc_` id). Every transaction that uses that discount is credited to the affiliate.

---

## Tracking Script API Reference

```javascript
// Format: "tc_CAMPAIGN123_aff_AFFILIATE456_cid_CLICK789"
window.linkjolt.referral

// Returns: { trackingCode, affiliateId, clickId }
window.linkjolt.getTrackingInfo()

// Returns boolean
window.linkjolt.isAffiliateVisit()

// Browser-side conversion reporting (used by Squarespace / Teachable / BigCommerce paths)
window.linkjolt.trackPurchase(amount, { orderId: 'ORDER_ID' })
```

---

## Testing

1. Visit your site with test parameters: `https://your-site.com/?tc=TEST123&aff=AFF456`
2. Open browser console and verify:
   ```javascript
   console.log(window.linkjolt.referral);
   // Should output: "tc_TEST123_aff_AFF456"
   ```
3. Complete a real or test purchase in your platform.
4. Check LinkJolt dashboard for the conversion.

## Common issues

- Paddle's notification log shows deliveries refused with 401 → the secret saved in LinkJolt is not this destination's secret key, or none is saved. The Integration Hub's Paddle tab then shows "Needs attention": paste the destination's secret key there, or set it up again with an API key.
- Sales record but refunds never reverse commissions → the destination is missing `adjustment.updated` (Paddle approves a refund in that event) or `adjustment.created` (credits and chargebacks).
- "customData empty" → make sure `window.linkjolt?.referral` is set before opening the Paddle Checkout overlay.