Paddle

Paddle is a merchant of record platform — it handles tax collection and compliance on your behalf. PayGlue connects Paddle to Ghost: when a customer completes a transaction or activates a subscription in Paddle, Ghost membership is granted automatically.

Note: Paddle does not offer simple checkout links you can paste into a button. Checkout requires a small JavaScript snippet embedded in your Ghost site. Step 5 covers this.

Prerequisites

• A Paddle account at paddle.com with at least one product and price created
• A Ghost blog connected in PayGlue (Connect Ghost)

Step 1: Create an API key

In your Paddle dashboard, go to Developer tools → Authentication.

Click Generate API key, give it a name (e.g. PayGlue), and copy the key immediately — Paddle shows it only once.

[Screenshot — Paddle Developer tools → Authentication: Generate API key button and the resulting key field]

The key starts with pdl_live_ for live mode or pdl_sdbx_ for sandbox. PayGlue detects the mode automatically from this prefix — no separate setting needed.

Step 2: Add a notification destination

Go to Developer tools → Notifications and click + New destination.

[Screenshot — Paddle Developer tools → Notifications: empty state with "+ New destination" button]

Fill in the form:

• Type: URL
• URL: paste the webhook URL from your PayGlue Paddle connection page:

https://api.payglue.io/webhooks/paddle?tenant=YOUR-SLUG

Replace YOUR-SLUG with your PayGlue organization slug (visible in the dashboard URL or on the Paddle connection page).

• Events: select all five of the following:
• transaction.completed
• subscription.activated
• subscription.resumed
• subscription.canceled
• subscription.paused

Click Save destination.

[Screenshot — Paddle: New destination form with URL filled in and the events checked]

Note: Do not select subscription.past_due. An overdue payment is not an ending: Paddle is still emailing the customer and retrying the card, and the customer has not decided anything yet. PayGlue records the event and does nothing with it, so selecting it only adds noise to your event log. If you already have it selected, you can leave it; it is skipped either way.

After saving, open the destination and copy the secret key (starts with pdl_ntfset_). You will need this in the next step.

[Screenshot — Paddle: Saved notification destination with the secret key field visible]

Step 3: Enter credentials in PayGlue

In your PayGlue dashboard, go to Providers and click Connect Paddle.

Fill in the two fields:

• API Key — from Step 1
• Webhook Secret — the pdl_ntfset_... secret key from Step 2

Click Save credentials.

Step 4: Run a health check

Click Run health check to confirm PayGlue can reach your Paddle account. A green "Connection established" banner means everything is working.

Step 5: Add Paddle checkout to your Ghost site

Paddle does not generate standalone checkout URLs. Instead, checkout opens as an overlay on your page, triggered by a JavaScript call. You embed Paddle's script once in Ghost, then add a button wherever you want a buy button to appear.

5a: Find your client-side token and price ID

You need two values from Paddle before touching Ghost:

Client-side token — this is separate from the API key. In Paddle, go to Developer tools → Authentication → Client-side tokens and copy the token for your environment (starts with live_ or test_).

[Screenshot — Paddle: Client-side tokens section with token value]

Price ID — in Paddle, go to Catalog → Products, open a product, and copy the ID of the price you want to sell. Price IDs start with pri_.

[Screenshot — Paddle: Product page showing price list with price IDs (pri_...)]

5b: Add Paddle.js to Ghost via Code Injection

In Ghost Admin, go to Settings → Code injection → Site header and add the following. Replace YOUR_CLIENT_TOKEN with the client-side token from above:

<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script>
  Paddle.Initialize({ token: 'YOUR_CLIENT_TOKEN' });
</script>

[Screenshot — Ghost Admin: Settings → Code injection → Site header with the Paddle script pasted in]

Click Save.

Warning: Use your client-side token here (starts with live_ or test_), not your API key. The API key is secret and must never appear in your site's HTML.

5c: Add a buy button

Wherever you want a checkout button — in a Ghost page, post, or theme template — add a button that calls Paddle.Checkout.open. Replace pri_xxxx with your actual price ID:

<button onclick="Paddle.Checkout.open({ items: [{ priceId: 'pri_xxxx', quantity: 1 }] })">
  Buy now
</button>

In a Ghost post or page you can add this via the HTML card in the editor. In a theme file you can place it directly in the template.

[Screenshot — Ghost editor: HTML card with the Paddle checkout button code]

When a visitor clicks the button, a Paddle checkout overlay opens. After a successful payment, Paddle sends a webhook to PayGlue, which then grants the Ghost membership automatically.

Step 6: Create a mapping

In your PayGlue dashboard, go to Buy Button, Paywall, or Pricing Table and select your Paddle product from the dropdown. Choose which Ghost newsletter to subscribe the buyer to and which welcome email to send, then save.

Supported events

Sandbox mode

Use a sandbox API key (pdl_sdbx_...) and a sandbox client-side token (test_...) during testing. PayGlue detects sandbox automatically — no extra setting in the dashboard. Make sure your Paddle notification destination in sandbox also points to the same webhook URL.

Remove test members from Ghost Admin before switching to live credentials.

Troubleshooting

Health check fails after saving credentials

Confirm you entered the API key (not the client-side token) in the API Key field. The API key starts with pdl_live_ or pdl_sdbx_; the client-side token starts with live_ or test_.

Checkout overlay does not open

Check the browser console for errors. Common causes:

• Paddle is not defined — the Paddle.js script was not added to Code injection, or the page loaded before the script finished
• Invalid token — the client-side token is wrong or belongs to the wrong environment (sandbox vs. live)

Webhook shows as Failed in Analytics

Open the event and check the error. Common cause: the webhook secret in PayGlue does not match the secret key shown in the Paddle notification destination. They must be identical.

Ghost member is not created after purchase

Confirm there is an active mapping for the Paddle price in the Buy Button, Paywall, or Pricing Table editor. PayGlue receives the event but takes no action without a mapping.

Webhook signature verification

Paddle's notification delivery does not currently attach a cryptographic signature to the requests it sends. PayGlue stores your Webhook Secret and will verify the Paddle-Signature header automatically if Paddle starts sending one — no action needed on your part. Until then, the per-tenant webhook URL itself acts as the shared secret between Paddle and PayGlue.