Integrations ยท Payment providers
Paddle transactions, renewals and refunds, linked to the visit.
Connect Paddle Billing with an API key limited to four permissions. Tally reads every completed transaction, tells new sales from renewals and upgrades, and links each to the visitor whose id rode in the checkout's custom data.
14 days free, no card needed.
01What Tally reads
- Every transaction Paddle completes: Paddle.js checkouts, ones made through the API, and subscription cycles.
- The kind from the transaction's origin: a new sale, a renewal, or an upgrade, with one-time charges on a subscription counted as expansion; a trial that converts counts as new.
- Refunds and chargebacks from adjustments once Paddle approves them; credits move no money and are left out.
- Amounts before tax, converted to US cents at the day's reference rate.
- Sandbox keys connect in test mode, so a sandbox checkout can be tried end to end.
02How a sale finds its visit
- Paddle.js customDataPass the visitor's id as tally_visitor_id in customData when you open the checkout. Paddle copies it from the subscription to each renewal, so they follow.
- Transaction custom_dataA transaction your server creates carries the same key in its custom_data.
- EmailThe customer's email, hashed at once, matches a tally('identify') call on your site. Medium confidence.
03What it can't read
- Paddle documents no way to carry the visitor's id through its hosted checkout or the default payment link, so those sales link only by email.
- Legacy API keys, made before Paddle added permissions, can't be limited, so they're refused.
- A refund still waiting for Paddle's approval isn't counted until it's approved; a rejected one never is.
- Adjustments to transactions older than the 365 days imported aren't brought in.
04Connecting it
- In Paddle, open Developer tools, Authentication, and create an API key with the four permissions below.
- Paste it on your site's Integrations page; each permission is checked with a call of its own.
- Tally adds its own notification destination in Paddle and imports the past 365 days of transactions.
- Add tally_visitor_id to customData where you open Paddle.js checkouts; the Coverage page has the lines for your page and for transactions your server makes.
What the API key needs
Tally asks for a API key that can do only this, and checks each permission with a real call when you paste it, so a missing one is named:
| Permission | Access | Why |
|---|---|---|
| Transaction | Read | Every payment: its amount, tax, origin and custom data. |
| Adjustment | Read | Refunds and chargebacks. |
| Customer | Read | The customer's email to match tally('identify'): hashed at once, never stored. |
| Notification setting | Write | Tally adds its own notification destination, so payments arrive within seconds. |
Where to make it: Paddle, Developer tools, Authentication.
05Questions
Does Tally work with Paddle Classic?
Tally reads Paddle Billing, API version 1, with keys that carry permissions. A legacy key without permissions is refused with a sentence that says so.
Why does Paddle need four permissions?
Transactions for the payments, adjustments for refunds and chargebacks, customers for the email match, and notification settings so Tally can add its own destination and hear of each payment within seconds.
Are chargebacks counted?
Yes: an approved chargeback adjustment is a negative chargeback, and a reversed one comes back as positive, so the pair nets out against the sale it belongs to.