Setup guide

Paddle Sync · Install it free · Plans and pricing

Paddle Sync is not affiliated with Paddle.com. It works with Paddle Billing only, not Paddle Classic.

1. Install

1. Open the install link. A short page lists what the app can do; click Continue to HubSpot.
2. Pick the HubSpot account. You need to be a Super Admin there, or have App Marketplace access.
3. Check the access list and click Connect app.
4. HubSpot shows an “unverified app” notice for apps that are not installed from the HubSpot Marketplace. Check that the redirect domain is kayabyte.dev, type I accept the risk and click Connect.

HubSpot then opens the app’s settings. The app creates a property group called Paddle with 13 properties on contacts and on companies. Every new account gets 14 days of the Scale plan. After that the account moves to Free unless you choose Growth or Scale.

2. What the app can access in HubSpot

• Contacts: read and update, and create. The app finds a customer’s contact by email, creates it if it does not exist, writes the Paddle properties and adds timeline notes.
• Companies: read, update and create, to find or create the company, write the Paddle properties and add notes.
• Deals: read and update, only used if you switch on deals. Pipelines are read so you can choose where deals go.
• Property definitions: the app creates its own properties on contacts and companies, and reads deal pipelines.
• Owners: read, to let you pick app admins.

The app does not read emails, calls, tickets or meetings.

3. Create a Paddle API key

In your Paddle dashboard, create an API key for Paddle Billing under the developer tools. Give it read access to customers, subscriptions, transactions and adjustments, and read and write access to notification settings. The app needs the write permission only to create and later remove its webhook destination. Use a sandbox key first if you want to try the app without live data: the key prefix tells the app which one you gave it, and the settings and cards show a clear sandbox label.

Paddle’s own documentation covers authentication and permissions.

4. Connect Paddle

1. Open Settings > Integrations > Connected apps > Paddle Sync > Settings.
2. Under Paddle connection, paste the API key and click Connect. The key is stored encrypted and is never shown again, only its last four characters.
3. The app creates one notification destination in Paddle and starts the import: customers, subscriptions and the last 12 months of transactions. Progress shows in the settings. A large account takes a while: we estimate roughly an hour and a half for 5,000 subscriptions, because of Paddle’s rate limits (not run live at that size).

If the key is missing a permission, the settings show an error that lists the permissions to give. Replacing the key removes the old destination in Paddle. Switching between sandbox and live drops the other environment’s data and clears the Paddle properties it wrote.

5. Add the cards

Add the cards to the right sidebar of contacts and companies: Paddle subscription for contacts and Paddle revenue for companies. In HubSpot, open a record, open edit mode from the Actions menu, choose + Sidebar card, then the App cards tab. Accounts on the older layout use Settings > Objects > Record Customization instead. HubSpot’s article Add and manage app cards has the current steps.

6. Matching rules

In the settings you choose:

• whether the app may create companies from email domains (it never does this for free-mail domains such as gmail.com);
• an optional Paddle custom data key that holds a company name, used before the email domain;
• nothing else is needed to match contacts: they are matched by email.

Saving a rule re-applies it to subscriptions that are already synced.

7. Deals (optional)

Switch on deals, choose a pipeline and the stage for active subscriptions, and optionally stages for the other statuses. The app keeps one deal per subscription, named “Paddle: plan - email”, with the amount set to ARR in the subscription’s currency. A status without a stage leaves the deal where it is. A subscription that was already canceled when first seen does not get a deal. If someone deletes a deal in HubSpot, the app recreates it on the next update. If a deal with the same name already exists in that pipeline, for example after you disconnected, deleted the data and reconnected, the app reuses it instead of creating a duplicate.

8. Use the data in workflows and reports

The Paddle properties are normal HubSpot properties. Paddle subscription status, Paddle last failed payment, Paddle cancellation date and Paddle trial ends are the usual triggers. Workflows need HubSpot Professional or Enterprise (HubSpot: create workflows). The guides show examples: workflows for failed payments and cancellations and showing MRR on contacts and companies.

9. Plans and limits

The plan counts subscriptions that are active, trialing or past due. If you go over the limit, subscriptions already synced keep syncing and new ones are held back until there is room; the settings show an upgrade button. A canceled subscription frees its place. Upgrade, change or cancel in the Plan and usage section of the settings.

10. Disconnect and delete data

• Disconnect removes the destination in Paddle and the stored key and secret. It keeps the synced records so the cards keep their history, and it deletes the stored raw events.
• Disconnect and delete Paddle data (type DELETE) also removes the synced customers, subscriptions and transactions from our database.
• Uninstall (type DELETE in the settings, or uninstall in HubSpot) removes the webhook first when it can and deletes everything the app stored for the account. Uninstalling in HubSpot is normally picked up within an hour.

The properties, notes and deals the app wrote stay in your HubSpot account. A paid subscription is cancelled at the end of the paid period.

Questions

support@kayabyte.dev. We answer within one working day.