Connect Paddle
Paste a read-only Paddle API key to import software and SaaS sales, refunds and tax by product and country.
Paddle is the merchant of record for software you sell outside the app stores: desktop apps, web apps, SaaS plans and licences. It connects with a single read-only API key rather than OAuth. You create the key in the Paddle dashboard, paste it into Revenue Sensor, and choose which Paddle products to sync. The key is stored encrypted and never leaves our server; your Paddle login is never involved.
Before you begin
- Access to the Paddle dashboard for the seller account whose sales you want to track, with permission to create API keys under Developer tools.
- Know whether you want the live account or the sandbox. Paddle issues separate keys for each, and the key decides which one we read; there is nothing else to pick.
Create a read-only API key
- 1
Open Developer tools
In the Paddle dashboard, go to Developer tools → Authentication and create a new API key. Give it a name you will recognise later, such as "Revenue Sensor".
- 2
Grant read permissions only
Tick read access for Transactions, Adjustments, Products and Addresses. Addresses is listed under Customers and gives us the buyer's country, so leave it in even though it sounds unrelated. No write permissions are needed.
- 3
Copy the key once
Paddle shows the key a single time when it is created. Copy it straight away; if you lose it, revoke it and create another.
Connect the account
- 1
Paste it in
Integrations → Paddle → Connect in the Revenue Sensor console, and paste the API key. Revenue Sensor reads the key prefix to tell a live key from a sandbox key and confirms which one it will use before you continue.
- 2
Choose your products
Paddle products, not store apps, are the units you sync. Pick the products you want in the ledger; each one appears as its own line in revenue and can be mapped to an app if it belongs to one. Only what you select is fetched, and only what you select counts toward your plan.
- 3
Let the first sync run
Paddle keeps your full history, so the first sync backfills up to a year of paid transactions and refunds. It usually takes a few minutes and you can leave the page while it runs.
What gets imported
| Field | Notes |
|---|---|
| Revenue | Paid transactions, booked on the day the money was captured rather than the day the invoice was issued. Shown per product, per day and per buyer country, excluding tax. Paddle's own fee is not deducted, the same way Google Play is shown gross of Google's fee. |
| Tax | Paddle collects sales tax and VAT as merchant of record and states it on every line item, so tax is imported separately and the tax-inclusive view is available for this source. |
| Refunds and chargebacks | Approved refunds and chargebacks reduce revenue on the day they are approved, with the amount also carried as a refund figure for context. A reversed chargeback puts the money back. Credits and chargeback warnings are not treated as refunds. |
| Country | Taken from the customer's billing address. Only the country code is used. |
Every Paddle currency is handled
Transactions are imported in the currency they were charged in and converted like every other source. Zero-decimal currencies such as JPY and KRW are read correctly, so a Japanese sale is not reported at a hundredth of its value.
Real-time updates (optional)
Revenue Sensor syncs Paddle every 30 minutes. If you would rather see a new sale or refund within a minute or two, point a Paddle notification destination at us. The numbers still come from Paddle's API; the webhook only tells us to sync sooner.
- 1
Copy the webhook URL
Open the Paddle connection in the Revenue Sensor console. The Real-time updates panel shows a URL that is unique to this connection; copy it.
- 2
Create a notification destination
In Paddle go to Developer tools → Notifications → New destination. Paste the URL, choose Webhook as the type, and subscribe to the transaction, adjustment and subscription events.
- 3
Save the secret
Paddle shows a signing secret when the destination is created. Paste it into the Real-time updates panel and save. We use it to verify every delivery and drop anything unsigned; it is stored encrypted and never shown again.
Troubleshooting
- The key is rejected: check that it has read access to all four of Transactions, Adjustments, Products and Addresses. A key without Addresses passes a basic check but fails the sync.
- No products are listed: the key belongs to a different account, or to the sandbox when you expected live (or the other way round). The prefix of the key tells you which.
- A sale is missing: only paid, completed transactions are imported. Drafts, unpaid invoices and cancelled transactions are not revenue yet.
- Revenue looks higher than your payout: that is expected. Tax is kept separate and Paddle's fee is not deducted, so the figure is gross revenue before Paddle's cut.
- A refund shows on a different day than the sale: refunds are booked on the day they are approved, not backdated to the original purchase.