Menu

Mattering Automations Paddle integration

Connect Paddle to Mattering Automations: catalog, customers, subscriptions, transactions, refunds and credits, and event reads as workflow steps, authenticated with a Paddle API key and testable end to end in Paddle's sandbox.

The Mattering Automations Paddle integration adds Paddle Billing to your automation canvas: manage catalog products and prices, keep customer records with their addresses and businesses, run the subscription lifecycle (update, pause, resume, cancel), read transactions with invoice PDF links, issue refunds and credits through adjustments, and poll the account event feed. It targets Paddle Billing at api.paddle.com with every request pinned to Paddle-Version 1; the legacy Paddle Classic API is not supported.

Setup takes a few minutes: create an API key in the Paddle dashboard, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.

Five of the 39 nodes are flagged destructive because they move real money or change real billing. Paddle: Create Adjustment (Refund or Credit) returns money to a customer's payment method and cannot be edited or deleted once created, and an immediate cancel through Paddle: Cancel Subscription is permanent. Every node carries a use_sandbox switch to Paddle's free sandbox, so rehearse the money paths there first and verify the integration with read nodes only.

Before you start

  • A Paddle Billing account. Accounts on the legacy Paddle Classic platform use a different API and are not supported by this integration.
  • Access to Developer tools in the Paddle dashboard to create an API key.
  • A Mattering workspace with access to the Automations app.
  • Recommended for anything that touches money: a Paddle sandbox account, which is free, separate from production, and issues its own API keys.

Create a Paddle API key

Mattering authenticates to Paddle with an API key, sent as a bearer credential on every request; requests are also pinned to Paddle-Version 1 so response shapes stay stable. Keys carry granular permissions chosen at creation, and the environment is baked into the key: a sandbox key only works against the sandbox host and a live key only against production.

In the Paddle dashboard, open Developer tools, then Authentication.
Create an API key and grant it read and write permissions on the entities your automations will touch: catalog, customers, subscriptions, transactions, adjustments.
Copy the key.
A narrowly permissioned key can pass the connection test, which only lists products, and still be refused with a 403 on other surfaces. If nodes fail with permission errors, create a new key with the permissions those surfaces need and update the credential.

Connect Paddle to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Paddle from the list.
Click Create new credential, paste your API key, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering lists products with the key, a read that succeeds even on an empty catalog. The test probes production, so a sandbox key fails here even though it works on nodes with use_sandbox enabled.
Click Connect. All 39 Paddle nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: a Paddle section should list the query and action nodes. Drop Paddle: List Products onto the canvas and run a test step. It needs no parameters, and an empty catalog still returns a successful, empty list; what matters is that the call authenticates. From there, Paddle: List Customers and Paddle: List Subscriptions confirm the wider read surface.

Everything in the verify path is read-only. The five destructive nodes (Paddle: Create Adjustment (Refund or Credit), Paddle: Cancel Subscription, Paddle: Pause Subscription, Paddle: Resume Subscription, and Paddle: Update Subscription) should be exercised in the sandbox first: enable use_sandbox on the node and use a sandbox key, where even refunds run their full lifecycle with no real money.

Node reference

39 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 24

Paddle: Get Address

paddle_get_address

Retrieve one address for a customer by id.

Paddle: Get Business

paddle_get_business

Retrieve one business for a customer by id.

Paddle: Get Credit Note PDF Link

paddle_get_credit_note_pdf

Get a temporary link to the credit note PDF for a refund or credit adjustment (data.url; the link expires, so use it in the same run). Available once the adjustment is approved.

Paddle: Get Customer

paddle_get_customer

Retrieve one customer by id.

Paddle: Get Invoice PDF Link

paddle_get_invoice_pdf

Get a temporary link to the invoice PDF for a transaction (data.url; the link EXPIRES after one hour, so use it in the same run, do not store it). Available for completed automatically-collected transactions and billed or completed manually-collected ones; zero-value transactions have no invoice.

Paddle: Get Notification

paddle_get_notification

Retrieve one notification by id, including the full event payload that was (or should have been) delivered and its attempt history.

Paddle: Get Notification Setting

paddle_get_notification_setting

Retrieve one notification destination by id, including its subscribed events and destination URL or email.

Paddle: Get Price

paddle_get_price

Retrieve one price by id, optionally embedding its product.

Paddle: Get Product

paddle_get_product

Retrieve one product by id, optionally embedding its prices.

Paddle: Get Subscription

paddle_get_subscription

Retrieve one subscription by id, including items, billing period, any scheduled_change (pending cancel, pause or resume) and customer-facing management URLs.

Paddle: Get Transaction

paddle_get_transaction

Retrieve one transaction by id with line items, calculated totals and payment attempts, optionally embedding the customer, address, business, discount or adjustments.

Paddle: List Addresses

paddle_list_addresses

List a customer's addresses. Paddle uses the address country and postal code to work out the right tax rate.

Paddle: List Adjustments

paddle_list_adjustments

List adjustments (refunds, credits, chargebacks and their reversals), filtered and paginated. Page size defaults to 10, max 50, on this endpoint. Track refund approval here: live refunds start at pending_approval.

Paddle: List Businesses

paddle_list_businesses

List a customer's businesses: the B2B billing details (company name, tax and company numbers) attached to transactions and subscriptions. Optional; consumers have none.

Paddle: List Customer Credit Balances

paddle_list_credit_balances

List a customer's credit balances per currency: available (usable at checkout), reserved (held for drafts) and used. Amounts are strings in the lowest denomination.

Paddle: List Customers

paddle_list_customers

List customers, filtered and paginated. Supports exact email match and a free-text search over name, email and id.

Paddle: List Event Types

paddle_list_event_types

List every event type Paddle can emit (for example transaction.completed, subscription.canceled), with descriptions and available API versions. Use it to pick events for a webhook destination.

Paddle: List Events

paddle_list_events

List events that occurred on the account, newest first: every create, update and billing lifecycle change, each with the changed entity under data. The polling alternative to webhooks for driving automations.

Paddle: List Notification Settings

paddle_list_notification_settings

List notification destinations (webhook endpoints and email addresses) with their subscribed events, active flag and pinned API version. Read-only here: create and edit destinations in the Paddle dashboard, where the signing secret is issued.

Paddle: List Notifications

paddle_list_notifications

List notifications sent (or attempted) to your webhook and email destinations, with delivery status and attempt counts. The debugging surface for missed webhooks.

Paddle: List Prices

paddle_list_prices

List prices, filtered and paginated. Price ids from here feed subscription item changes and transaction lines.

Paddle: List Products

paddle_list_products

List products in the catalog, filtered and paginated. Needs no parameters (an empty catalog returns an empty list), so this is also the credential health check. Product ids from here feed the price nodes.

Paddle: List Subscriptions

paddle_list_subscriptions

List subscriptions, filtered and paginated: by customer, price, status (active, canceled, past_due, paused, trialing) or pending scheduled change (cancel, pause, resume).

Paddle: List Transactions

paddle_list_transactions

List transactions (Paddle's revenue records: checkouts, renewals, invoices), filtered and paginated. Amounts are strings in the lowest denomination. Page size defaults to and caps at 30 on this endpoint.

Action nodes 15

Paddle: Cancel Subscription

paddle_cancel_subscription

END a real subscription and its recurring revenue. With the default next_billing_period, Paddle schedules the cancel for the end of the current period, and you can still undo it via Paddle: Update Subscription with scheduled_change null. With immediately, the subscription is canceled on the spot and that is PERMANENT: Paddle cannot reinstate a canceled subscription; the customer would have to sign up again.

Paddle: Create Address

paddle_create_address

Create an address for a customer. Only country_code is required; Paddle uses country and postal code for tax calculation. Reversible: archive with Paddle: Update Address.

Paddle: Create Adjustment (Refund or Credit)

paddle_create_adjustment

MOVES REAL MONEY. A refund sends money from your balance back to the customer's payment method (works on completed automatically-collected transactions; live refunds go to pending_approval for Paddle review, some auto-approve). A credit reduces what a manually-collected customer owes on a billed or past_due transaction and needs no approval. Adjustments CANNOT be edited or deleted once created. In the sandbox, refunds auto-approve about every ten minutes, so test there.

Paddle: Create Business

paddle_create_business

Create a business for a customer, holding company details for B2B billing (shown on invoices; the tax identifier can reverse-charge VAT where applicable). Reversible: archive with Paddle: Update Business.

Paddle: Create Customer

paddle_create_customer

Create a customer. Email must be unique: Paddle returns a conflict error if a customer with the email already exists (archived included). Reversible: archive with Paddle: Update Customer.

Paddle: Create Price

paddle_create_price

Create a price for a product: how much and how often it is billed. Omit billing_cycle for a one-time price; include it for a recurring one. Creating a price moves no money. Reversible: archive it with Paddle: Update Price.

Paddle: Create Product

paddle_create_product

Create a product in the catalog. Products hold the what (name, tax category); attach one or more prices for the how much. Reversible: archive it with Paddle: Update Product.

Paddle: Pause Subscription

paddle_pause_subscription

STOP BILLING on a real subscription. By default the pause takes effect at the end of the current billing period (a scheduled_change you can still remove via Paddle: Update Subscription with scheduled_change null); immediately pauses on the spot. While paused the customer is not billed. Undo by resuming, which by default charges them immediately.

Paddle: Resume Subscription

paddle_resume_subscription

RESTART BILLING on a paused subscription (or one scheduled to pause). By default this starts a new billing period and CHARGES the customer immediately; set on_resume to continue_existing_billing_period to avoid a charge when their paid period has not ended. Billing dates are recalculated from the resume date.

Paddle: Update Address

paddle_update_address

Update an address (sparse). Also the archive path: set status to archived to retire the address (Paddle has no address delete), or active to restore it.

Paddle: Update Business

paddle_update_business

Update a business (sparse). Also the archive path: set status to archived to retire the business (Paddle has no business delete), or active to restore it.

Paddle: Update Customer

paddle_update_customer

Update a customer (sparse). Also the archive path: set status to archived to retire the customer record (Paddle has no customer delete), or active to restore it.

Paddle: Update Price

paddle_update_price

Update a price (sparse). Changing unit_price affects what NEW checkouts and renewals bill, not past transactions. Also the archive path: set status to archived to retire the price (Paddle has no price delete), or active to restore.

Paddle: Update Product

paddle_update_product

Update a product (sparse: only fields sent are changed). Also the archive path: Paddle has no product delete, so set status to archived to retire a product (and active to restore it).

Paddle: Update Subscription

paddle_update_subscription

Change a REAL customer's billing: swap plans, change quantities, reschedule billing or apply a discount. Changing items, next_billed_at or the discount requires proration_billing_mode, and the prorated_immediately and full_immediately modes create a transaction that CHARGES the customer right away. Sending scheduled_change as null is the undo for a pending scheduled cancel or pause.

Using the integration

On the automation canvas

Paddle nodes chain with every other node: a scheduled Paddle: List Subscriptions sweep over past_due renewals can open tasks in Mattering Productivity with the customer and the failed transaction attached, and churn signals surfacing in Paddle: List Events can log to a Mattering database. Amounts arrive as strings in the currency's lowest denomination (a value of 2499 is 24.99 in a two-decimal currency), so format them before they reach a human surface.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can check subscription status, look up customers, and read transactions through the same nodes your workflows use. The list and get nodes are all read-only, which makes them the safest Paddle surface to hand an agent; keep the five destructive nodes behind approvals regardless of who is driving.

Rehearse in the sandbox first

Every node has a use_sandbox switch that points it at sandbox-api.paddle.com. A Paddle sandbox account is free, separate from production, and issues its own API keys, and it supports the whole surface including money flows: sandbox refund adjustments auto-approve about every ten minutes, so the full refund lifecycle, credit note included, is verifiable end to end without spending anything. Never run the destructive nodes against a production key as a test.

The five nodes that change real billing

Paddle: Create Adjustment (Refund or Credit) moves real money and fires once: an adjustment cannot be edited or deleted once created, and Paddle's API has no idempotency keys, so put a condition or an approval in front of it. Paddle: Cancel Subscription defaults to scheduling the cancel for the end of the billing period, which can still be undone; run with immediately, it is permanent, because Paddle cannot reinstate a canceled subscription. Paddle: Pause Subscription stops billing, Paddle: Resume Subscription by default starts a new billing period and charges the customer immediately (set on_resume to continue_existing_billing_period to avoid that while their paid period lasts), and the prorated_immediately and full_immediately proration modes on Paddle: Update Subscription create a transaction that bills right away. The undo for a pending scheduled cancel or pause is Paddle: Update Subscription sending scheduled_change as null through its body passthrough.

Archive instead of delete

Paddle has no delete endpoints for products, prices, customers, addresses, or businesses, so neither does this integration. The update nodes are the archive path: set status to archived to retire an entity, which hides it from default list responses and blocks new use while preserving history, and set status back to active to restore it. Nothing in the node catalog pretends an archive is a delete.

Events, notifications, and the missing trigger

There is no inbound Paddle trigger in this integration. To react to billing changes, poll Paddle: List Events on a schedule: it returns events newest first with the changed entity in each payload, and Paddle: List Event Types catalogs what can occur. Webhook destinations are dashboard configuration in Paddle, where the signing secret is issued, so Paddle: List Notification Settings reads them rather than creating them, and Paddle: List Notifications with delivery status and attempt counts is the debugging surface for missed webhooks.

Troubleshooting

Test Connection fails with a 401
The key is invalid, picked up stray whitespace when pasted, or belongs to the wrong environment. The environment is baked into the key, and the connection test probes production, so a sandbox-only key fails the test while nodes with use_sandbox enabled work fine. Paste a live key to pass the test, or verify a sandbox setup by running Paddle: List Products with use_sandbox enabled instead.
Test Connection passes but a node returns a 403
The key is under-permissioned. Paddle keys carry granular permissions chosen at creation, and the connection test only lists products, so a key missing other permissions passes it while the nodes needing them are refused. Create a new key with read and write permissions on the entities your automations touch and update the credential.
Paddle: Create Customer returns a conflict error
A customer with that email already exists, and archived customers count too, because Paddle requires customer emails to be unique. Find the existing record with Paddle: List Customers, which supports exact email match; if it is archived, restore it by setting status to active with Paddle: Update Customer instead of creating a duplicate.
A refund sits in pending approval
That is the live refund lifecycle. Refunds created with Paddle: Create Adjustment (Refund or Credit) start at pending approval for Paddle review (some auto-approve), and Paddle: List Adjustments tracks them through it. Credits on manually collected transactions need no approval. In the sandbox, refunds auto-approve about every ten minutes, which is why the refund path should be rehearsed there.
An adjustment was created with the wrong amount
Adjustments cannot be edited or deleted once created; contact Paddle to sort out a mistake. Treat Paddle: Create Adjustment (Refund or Credit) as a fire-once node: Paddle's API has no idempotency keys, so gate it behind a condition, an approval task, or a manual run, and test the workflow in the sandbox before it ever sees a production key.
A subscription was canceled by mistake
What happens next depends on the mode. The default schedules the cancel for the end of the billing period, and until it takes effect it can be undone by sending scheduled_change as null through the body passthrough on Paddle: Update Subscription. An immediate cancel is permanent: Paddle cannot reinstate a canceled subscription, and the customer would have to sign up again. Keep Paddle: Cancel Subscription on its default mode unless immediate really is the intent.
Paddle: Resume Subscription charged the customer
That is the default: resuming starts a new billing period and bills immediately, with billing dates recalculated from the resume date. When the customer's previously paid period has not ended, set on_resume to continue_existing_billing_period to resume without a charge.
An invoice or credit note PDF link stopped working
The links from Paddle: Get Invoice PDF Link and Paddle: Get Credit Note PDF Link are temporary and expire after about one hour, so fetch them in the same run that uses them rather than storing them. Also check availability: invoices exist for completed automatically collected transactions and for billed or completed manually collected ones, zero-value transactions have no invoice, and a credit note appears once its adjustment is approved.

Paddle is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products