Paddle integration

The Paddle integration has two parts, and both are required:

Authorize Paddle so Partnero receives the payments your customers make, including renewals.
Add referral tracking to your site so Partnero knows which partner referred each customer.

Authorization on its own gives Partnero payments it cannot attribute to anyone. Step 2 is what creates the referred customer the payments attach to.

Your program’s own integration guide, with your program ID already filled in, lives in the app under Integration → Guides. It is the source of truth for the snippets below.

This page covers Paddle Billing, the default Paddle experience. If you signed up before 8 August 2023 you may still be on Paddle Classic — see Integrate Paddle Classic.

Step 1: Authorize Paddle

In Paddle, go to Developer Tools → Authentication and generate an API key.
In Partnero, go to Integration and scroll to Apps & Integrations.
Click Authorize next to Paddle, paste the API key, and click Authorize.

You do not configure Paddle notifications yourself. Partnero creates the webhooks it needs when you authorize.

Step 2: Add referral tracking to your site

This is what tells Partnero which partner referred a customer. Without it, Paddle sends Partnero payments it cannot attribute to anyone.

Install the tracking script

Every method starts here. This snippet identifies visitors arriving through a partner’s referral link and stores the partner key in a first-party cookie. Copy your own snippet from the app — don’t retype the one below. It is generated per program and already contains your program ID:

Open the program and go to Integration.
Copy the PartneroJS snippet shown there. It also appears inside every guide on the Guides tab.

Paste it before the closing </head> tag on every page a referred visitor might land on — ideally site-wide. For reference, the snippet looks like this, where YOUR_PROGRAM_ID is filled in for you:

<!-- PartneroJS -->
<script>
(function(p,t,n,e,r,o){p['__partnerObject']=r;function f(){var c={a:arguments,q:[]};var r=this.push(c);return "number"!=typeof r?r:f.bind(c.q);}
f.q=f.q||[];p[r]=p[r]||f.bind(f.q);p[r].q=p[r].q||f.q;o=t.createElement(n);var _=t.getElementsByTagName(n)[0];o.async=1;
o.src=e+'?v'+(~~(new Date().getTime()/1e6));_.parentNode.insertBefore(o,_);})(window,document,'script','https://app.partnero.com/js/universal.js','po');
po('program', 'YOUR_PROGRAM_ID', 'load');
</script>
<!-- End PartneroJS -->

Unlike the Stripe integration, PartneroJS does not pass anything to Paddle on its own. If customers buy through a Paddle checkout you must also add one of the Overlay checkout scripts below.

Then choose a method

Overlay: Paddle.Checkout.open()
Overlay: HTML data attributes
User sign-up

Use this if you open the checkout with Paddle’s Paddle.Checkout.open() method.The script wraps Paddle.Checkout.open so every checkout carries the partner key in customData. Place it at the bottom of the page, directly above the closing </body> tag.

<script>
const partnerKey = (document.cookie.match(/(^| )partnero_partner=([^;]+)/) || [])[2];
if (partnerKey) {
  const originalOpen = Paddle.Checkout.open;
  Paddle.Checkout.open = function(options) {
    options.customData = options.customData || {};
    options.customData.customer_key = decodeURIComponent(partnerKey);
    return originalOpen.call(this, options);
  };
}
</script>

Use this if your checkout is triggered by Paddle’s HTML data attributes on .paddle_button elements.The script sets data-custom-data on each button. Place it at the bottom of the page, directly above the closing </body> tag.

<script>
document.querySelectorAll('.paddle_button').forEach(button => {
  const cookieValue = (document.cookie.match(/(^| )partnero_partner=([^;]+)/) || [])[2];
  if (cookieValue) {
    button.setAttribute('data-custom-data', JSON.stringify({
      customer_key: decodeURIComponent(cookieValue)
    }));
  }
});
</script>

Use this if customers sign up on your platform before paying. Partnero creates the customer and links it to the partner at sign-up, so every later Paddle purchase by that customer is attributed automatically. No Overlay script is needed.For that to work Partnero has to recognise the payer, so pass the same key in Paddle’s custom_data as customer_key when you create the Paddle customer or transaction.Run this immediately after the user signs up. Attribution is read from the partnero_partner cookie:

<script>
po('customers', 'signup', {
  data: {
    key: 'customer_123456',
    name: 'John',
    email: '[email protected]'
  }
});
</script>

Or create the customer from your backend, passing the partner key you read from the cookie:

curl -X POST https://api.partnero.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner": {
      "key": "PARTNER_KEY_FROM_COOKIE"
    },
    "key": "customer_123456",
    "email": "[email protected]",
    "name": "John Doe"
  }'

Your API key is in the app under Integration → API. Keep it server-side.

In a refer-a-friend program the cookie is partnero_referral instead of partnero_partner, and the referrer is sent as referring_customer.key. The Overlay scripts are otherwise identical.

What gets tracked

Once both steps are done, Partnero records completed purchases and new subscriptions made by your referred customers, and reverses the commission automatically when a payment is refunded.

Attribution from your own backend

When a visitor arrives through a referral link, PartneroJS stores the partner key in a first-party cookie named partnero_partner (partnero_referral in a refer-a-friend program). That cookie is where the partner key comes from — read it on your server from the incoming request headers. If you create Paddle transactions server-side, pass the key in Paddle’s custom_data:

customer_key — the key of the customer in Partnero. If no customer matches it, Partnero falls back to treating the value as a partner key, which is why the Overlay scripts above can use the same field.
partner_key — attribute the sale to that partner even when no customer record exists yet.
client_reference_id — equivalent to customer_key used as a partner key, for parity with Stripe.

Partnero reads these from the transaction and from the Paddle customer’s own custom_data. If your Paddle custom data already uses a different field name for the customer, map it instead of renaming your own field: open the Paddle integration in the app and set Paddle integration mapping.

Troubleshooting

Purchases are not appearing in Partnero

Check step 2 actually ran. Open the customer in Partnero and confirm it exists and has a partner attached. A payment Partnero cannot tie to a customer is not attributed to anyone.

Checkouts carry no attribution

PartneroJS alone does not reach Paddle. Confirm one of the Overlay scripts is on the page that opens the checkout, below the checkout markup and above the closing </body> tag, and that the partnero_partner cookie is set when you arrive through a referral link.

The customer exists but the sale is attributed to nobody

Partnero could not recognise the payer. The customer_key in Paddle’s custom data must match the customer key in Partnero character for character. Paddle does not fall back to matching on email the way Stripe does, so an email-only match is not enough.

Nothing is tracked after a renewal

Renewals arrive on the Paddle webhooks Partnero creates at authorization, so this needs step 1. Creating the customer alone is not enough.

I am on Paddle Classic

Paddle Classic uses passthrough rather than custom_data, and its webhooks are not created automatically. Follow Integrate Paddle Classic instead.

Overview

AI tools

Getting started

Billing integrations

Coupon tracking

E-commerce

Website builders & CMS

Courses & communities

Forms & scheduling

CRM & automation

Payouts

Email & marketing

Webhooks

Paddle integration

Step 1: Authorize Paddle

Step 2: Add referral tracking to your site

Install the tracking script

Then choose a method

What gets tracked

Attribution from your own backend

Troubleshooting

Next steps

Paddle Classic

Transactions API

​Step 1: Authorize Paddle

​Step 2: Add referral tracking to your site

​Install the tracking script

​Then choose a method

​What gets tracked

​Attribution from your own backend

​Troubleshooting

​Next steps

Paddle Classic

Transactions API

Step 1: Authorize Paddle

Step 2: Add referral tracking to your site

Install the tracking script

Then choose a method

What gets tracked

Attribution from your own backend

Troubleshooting

Next steps