Selling through Paddle?

Paddle webhooks firing wrong or tax ending up on the wrong line? We sort it out.

Paddle promises to take the merchant of record burden off a SaaS team, which it does, until a webhook version mismatch, a tax category that should not apply, or a subscription change produces an invoice nobody can reconcile. We work through the event stream and the price configuration to the specific cause.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

paddle-events.log

still failing

What it is

Paddle at a glance

Paddle is a merchant of record payments platform for software and SaaS companies, founded in 2012 by Christian Owens and Harrison Rose in London. By acting as the legal seller, Paddle handles sales tax, VAT, GST and local payment regulations across a long list of countries so the software company does not have to register in each one.

The product has gone through a significant platform shift from Paddle Classic to Paddle Billing, with a redesigned API, new webhook versions and different product and price modelling. Teams can issue subscriptions, one off purchases, free trials, discounts and refunds through the API or the dashboard, and Paddle handles the tax calculation and remittance behind each transaction.

Type
Merchant of record payments and subscriptions for SaaS
First released
2012
License
Proprietary SaaS, revenue share plus transaction fee pricing
Maintained by
Paddle.com Market Limited
Typically used for
SaaS subscriptions, digital goods, tax compliance across jurisdictions, global checkout

The honest version

Paddle pros and cons

No technology is all upside. This is where Paddle earns its place and where it tends to cause trouble.

Where Paddle is strong

  • Merchant of record removes real tax workPaddle handles sales tax, VAT, GST registrations and remittance across many jurisdictions, which saves a growing SaaS from a genuinely painful compliance project.
  • Global checkout with local methodsCards, PayPal, Apple Pay, Google Pay and several regional methods come through the one checkout, which lifts conversion versus a card only flow.
  • Subscription primitives are solidPlans, trials, discounts, proration and invoice behaviour are first class in the API, so you are not inventing billing on top of raw charges.
  • Chargeback and fraud handled centrallyBecause Paddle is the merchant of record, disputes land with them first, which cuts the operational burden on small finance teams.
  • Refund and credit flows are cleanRefunds, partial refunds and credits are straightforward in the API and the dashboard, with the tax implications handled automatically.
  • Decent developer resourcesPaddle Billing has well written docs, a sandbox environment and SDKs for the main languages, which makes the integration faster than its Classic predecessor.

Where Paddle bites

  • The Classic to Billing migration is substantialProducts, prices, webhook event names and API surface changed enough that moving an existing Paddle Classic integration is a real project rather than a version bump.
  • Revenue share pricing bites at scaleA percentage per transaction plus fixed fees is reasonable for early stage SaaS and expensive once ARR grows, especially compared to Stripe plus a tax tool.
  • Tax category mapping is subtleThe product tax category drives whether VAT applies, which rate and which jurisdictions, and a wrong mapping produces invoices that are hard to correct retroactively.
  • Webhook version management requires carePaddle Billing versions webhooks explicitly, and teams that do not pin a version find their handlers break when a new one becomes default.
  • Payouts are less flexible than a direct processorPaddle pays out on its own schedule in its chosen currency, and treasury teams that want real time or multi currency routing find less headroom than with Stripe.
  • Customer visible brandingInvoices and card statements show Paddle alongside your brand because they are the legal seller, which some enterprise buyers query the first time they see it.

Sound familiar?

Common Paddle problems we fix

The Paddle problems that bring people to us, and what you have once each one is fixed.

webhook signature verification failed

Paddle webhooks are being rejected

A signing secret drift between the dashboard and the receiver, or a body that was parsed before verification stripped a byte. The fix is to verify against the raw body, not the parsed JSON.

Webhooks accepted and processed

subscription.activated with no local user

New subscription has no matching customer record

The checkout created a Paddle customer but your app never stored the mapping, so the first webhook arrives for an unknown user. We rebuild the mapping and backfill the missing records.

Every webhook maps to a real user

tax_category not applicable

Tax category is wrong for the product

A product was created with the default category and the real category should have been digital goods or SaaS specific. The wrong tax applied means refunds and reissues for affected invoices.

Tax categories match product reality

prorated_immediately created a $0.03 invoice

Plan changes produce bizarre invoices

Proration mode interacts with discounts and free trials in ways that generate tiny invoices customers find confusing. We pick a proration mode that matches your real contract behaviour.

Invoices match what the customer expects

webhook v1 deprecated

Still on a deprecated webhook version

Paddle Billing has moved on, and handlers pinned to the old version will stop working on the sunset date. We migrate the handlers and run both versions in parallel until the new one is verified.

Handlers on a supported version

refund failed, status 'past_due'

Refunds fail on past due subscriptions

A refund request against a subscription that is past due or already cancelled returns an error that most codebases do not retry correctly. We handle the specific status rather than retrying blindly.

Refunds handled across every state

payment_method_update event missing

Card updater events not being handled

Paddle's updater refreshes expiring cards but the event that confirms it is often ignored, so your own copy of the card metadata stays stale and renewals look surprising.

Card metadata matches reality

address verification failed

US tax addresses fail verification

Paddle's US tax validation is strict about state and ZIP matching, and a free form checkout that accepts any string eventually produces a rejected transaction. We tighten the form against the validation rules.

Addresses accepted on first try

What we do

Paddle help, from integration to tax posture

Call us for one bad webhook, or let us own the whole Paddle integration.

Rescue
Webhooks failing verification, subscriptions out of sync, or tax lines on invoices that cannot be defended. We stabilise the integration first and explain second.
Classic to Billing migration
Products, prices and webhook handlers moved to Paddle Billing in a measured pass, with both platforms live until renewals and refunds are proven on the new one.
Webhook reliability
Signed verification against the raw body, idempotent handlers, replay from the dashboard, and alerts on handler failures so no event is lost in silence.
Tax category and product setup
Products mapped to the right tax categories, prices configured for the markets you actually sell into, and a review pass against your accounting rules.
Subscription design
Trials, plan changes, discount handling and proration modes picked against your real contracts so invoices match customer expectations.
Managed Tech
Ongoing reviews of webhook delivery, chargeback rates, tax configuration and renewal success, plus a team to call when Paddle Billing ships a change that affects your integration.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Paddle alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Paddle questions

Something else? Call+1 737 727 7327

Should we use Paddle or Stripe plus a tax tool?

Paddle wins when sales tax, VAT and GST registration across many countries would otherwise be a serious compliance project, especially for a small team. Stripe plus a tax tool like Stripe Tax or Avalara wins when revenue is high enough that the merchant of record revenue share costs more than the compliance burden. We model both against your real revenue and jurisdictions before recommending one.

Why are our Paddle webhooks failing verification?

Two very common causes: the handler is verifying against a parsed JSON body rather than the raw request body, which strips whitespace and breaks the HMAC; or the signing secret in the environment does not match the one in the dashboard, often because staging and production got mixed. We walk the signing flow against a captured payload and prove where the mismatch is.

How painful is Paddle Classic to Paddle Billing?

Real work, but doable. The product and price concepts are different, the webhook event names changed, and the API surface is largely rewritten. We port in batches, keep Classic running for existing subscriptions, and only move renewals once the new flow is verified against sandbox and a limited live cohort.

How do we fix an invoice that applied the wrong tax?

Paddle supports refunds and credits that back out the tax correctly, but the fix also has to prevent the next invoice from repeating the mistake. We review the product tax category, correct the historical invoices through Paddle's refund and reissue flow, and update the integration so new purchases take the right category from the start.

Can you help us move from Paddle to Stripe or vice versa?

Yes, in either direction. Both migrations have their own quirks: moving off Paddle means taking on tax compliance that was handled for you, and moving onto Paddle means remodelling products and prices. We plan the transition against live subscriptions so customers do not see a surprising invoice.

How much does Paddle help cost?

The estimate is at no charge. Describe the integration, the problem and send a recent webhook payload where you can, and we come back with a price and a plan before starting.

Free estimate

Paddle integration giving you grief?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.