Paddle Billing

Paddle Billing

This connector uses the Paddle Billing API (https://api.paddle.com, sandbox https://sandbox-api.paddle.com). Paddle is a merchant of record for software and digital products: it sells to the customer, handles tax and pays you out. The connector reads and manages the catalog (products, prices, discounts), customers with their addresses and businesses, subscriptions, transactions and invoices, refunds and credits, reports, dashboard metrics, events and webhook notifications. It covers Paddle Billing only, not Paddle Classic.

Setup (2 minutes)

1. In Paddle open Developer tools, Authentication, API keys and create a key. Give it the permissions the tools need: read for products, prices, discounts, customers, addresses, businesses, subscriptions, transactions, adjustments, reports, notifications and events; write for the ones you want the AI to change.
2. Paste the key into PADDLE_API_KEY. It is sent as Authorization: Bearer <key>.
3. Set PADDLE_API_URL to https://api.paddle.com for the live account or https://sandbox-api.paddle.com for a sandbox account. Sandbox and live keys only work on their own host.
4. Run paddle_list_event_types to check the key.

Workflow

• Catalog: paddle_list_products (include prices), paddle_get_product, paddle_create_product, paddle_update_product; prices with paddle_list_prices, paddle_get_price, paddle_create_price, paddle_update_price; discounts with paddle_list_discounts, paddle_get_discount, paddle_create_discount, paddle_update_discount. Nothing is deleted in Paddle: set status to archived instead.
• Customers: paddle_list_customers (search by email), paddle_get_customer, paddle_create_customer, paddle_update_customer. Addresses: paddle_list_customer_addresses, paddle_create_customer_address, paddle_update_customer_address. Businesses (VAT number, company): paddle_list_customer_businesses, paddle_create_customer_business, paddle_update_customer_business. paddle_list_customer_credit_balances shows credit, paddle_create_customer_portal_session gives the customer a link to manage payment methods and subscriptions.
• Subscriptions: paddle_list_subscriptions, paddle_get_subscription (include next_transaction for the next charge). To change plan or quantity, run paddle_preview_subscription_update first and show the user the immediate charge, then paddle_update_subscription with the full new items list and a proration_billing_mode. Lifecycle: paddle_pause_subscription, paddle_resume_subscription, paddle_cancel_subscription, paddle_activate_subscription (ends a trial and bills now). A scheduled pause or cancel is removed with paddle_update_subscription and scheduled_change: null. paddle_create_subscription_charge bills a one-time charge on the saved payment method and paddle_cancel_subscription ends a subscription; both are installed switched off.
• Transactions and invoices: paddle_list_transactions (by customer, subscription, status, invoice number, billed or created date range), paddle_get_transaction, paddle_get_transaction_invoice for the PDF link. paddle_create_transaction creates a checkout to pay (its checkout.url) or, with collection_mode: manual and status: billed, an invoice; paddle_update_transaction changes a draft or ready one. Quotes without saving: paddle_preview_transaction, paddle_preview_prices.
• Refunds and credits: paddle_list_adjustments, paddle_create_adjustment (refunds are reviewed by Paddle and start as pending_approval), paddle_get_adjustment_credit_note.
• Reports and numbers: paddle_create_report, then paddle_get_report until status is ready, then paddle_get_report_csv; paddle_list_reports lists earlier ones. Dashboard metrics per day: paddle_get_revenue_metrics, paddle_get_mrr_metrics, paddle_get_active_subscribers_metrics.
• Events and webhooks: paddle_list_event_types, paddle_list_events (last 90 days), paddle_list_notification_settings, paddle_list_notifications, paddle_get_notification, paddle_list_notification_logs, paddle_replay_notification.

Before writing: transactions billed, subscription updates, cancellations, refunds and one-time charges affect real money on the live host. Show the user what will change (use the preview tools) and wait for a yes.

Reading the answers: every response has data and meta.request_id. Ids carry a prefix: pro_ product, pri_ price, dsc_ discount, ctm_ customer, add_ address, biz_ business, sub_ subscription, txn_ transaction, adj_ adjustment, rep_ report, ntf_ notification. Amounts are strings in the lowest currency unit ("1999" USD = 19.99; JPY has no decimals). Totals of a transaction are in details.totals (subtotal, discount, tax, total, grand_total) and per item in details.line_items. Dates are RFC 3339 in UTC. Filters that take several values are comma-separated.

Paging: list tools return up to per_page items (50 by default, 200 at most). When meta.pagination.has_more is true, take the after value from the meta.pagination.next URL and pass it as after.

Limits and errors: 240 requests per minute per IP (429 above that). Errors come as error.type, error.code and error.detail, with error.errors listing invalid fields. 403 forbidden means the API key lacks the permission for that entity; 401 means a wrong key or a sandbox key on the live host (or the reverse); 404 entity_not_found a wrong id or the other environment.