# Paddle Knowledge Patch > Paddle - Skill: `nevaberry/paddle-knowledge-patch-2` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add nevaberry/paddle-knowledge-patch-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/paddle-knowledge-patch-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/paddle-knowledge-patch-2 --- # Paddle Knowledge Patch Use this skill when implementing or reviewing Paddle Billing integrations that touch API versioning, authentication, subscriptions, checkout, pricing, tax, transactions, reporting, payouts, webhooks, or migration from Paddle Classic. ## Reference index | Reference | Topics | | --- | --- | | [API and security](references/api-and-security.md) | API defaults and per-request pinning, OAuth apps, hosted MCP authentication, API keys, client-side tokens, pagination totals | | [Subscriptions and portal](references/subscriptions-and-portal.md) | History, trials, scheduled changes, retries, resumption, proration, consent, portal sessions, recurring non-catalog items | | [Checkout and storefront](references/checkout-and-storefront.md) | Express and recovery flows, domains, Paddle UI, iOS purchase flows, regional methods, localization, Paddle.js updates and previews | | [Catalog, transactions, and tax](references/catalog-transactions-and-tax.md) | Transaction discounts, discount groups, tax-aware adjustments, non-catalog transactions, payment lifecycle, post-purchase documents | | [Reporting, payments, and payouts](references/reporting-payments-and-payouts.md) | Reports, account metrics, payment details, payout details, reconciliation, operational limits | | [Webhooks and operations](references/webhooks-and-operations.md) | Destination versions, simulation, replay, retention, sandbox behavior, Paddle Classic migration | ## Highest-impact compatibility rules ### Pin API behavior deliberately Paddle increments its sequential API version only for breaking changes. The current version is `1`; older versions are neither automatically upgraded nor currently deprecated. New accounts default to the latest version, and a request without an explicit version uses its account default. `Paddle-Version` overrides the account default for one request. It can select a later version for testing before the account default changes, but cannot select a version earlier than that default. ```sh curl https://api.paddle.com/event-types \ -H "Authorization: Bearer $PADDLE_API_KEY" \ -H "Paddle-Version: 1" ``` Webhook notification destinations are different: select an API version when creating each destination because they do not use the account default. ### Do not treat estimated list totals as exact For large datasets, the estimated total in a paginated list response is capped. Do not interpret that estimate as the complete result count. ### Provision on transaction completion Transactions now have a `paid` status. Paddle emits `transaction.paid` after successful payment but before its post-payment processing completes. `transaction.completed` contains the fields needed for provisioning. ### Account for negative proration values Proration is represented on a transaction rather than as separate adjustments. Transaction quantities, amounts, and totals may therefore be negative. A subscription permits at most 20 chargeable updates per hour and 100 per day. Pausing a subscription cancels past-due renewal transactions so they are not collected when the subscription resumes. ### Respect event and notification retention Notifications may be replayed, but events and notifications older than 90 days are unavailable through the API. ## Authentication quick reference ### Server-side and app access Apps may connect through OAuth instead of API keys, and merchants can manage connected third-party apps in the dashboard. The hosted Paddle MCP server uses browser-based OAuth for live accounts, requires an API key for sandbox, and exposes the API through three tools in its remote codemode interface. Enhanced API keys have a standardized format and support permissions, expiry dates, and usage tracking. Paddle may detect exposed keys in public GitHub repositories and alert or disable them. An AWS Secrets Manager integration can rotate keys on a schedule without downtime. ### Browser access Paddle.js authenticates with client-side tokens instead of seller IDs. Paddle Retain can use the same token instead of a separate Retain API key. Client-side tokens can be created and managed through API operations, with corresponding webhooks. ## Subscription quick reference ### Lifecycle and retries The subscription history API records changes chronologically across a subscription's lifetime, including when each change occurred, why it occurred, and who made it. Subscriptions with a scheduled pause or cancellation may still be updated. Resuming a paused subscription may start a new billing period or continue the existing one. Failed automatically collected subscription payments are retried even when Paddle Retain is not enabled. ### Trials and consent Paid trials can charge a reduced trial-period amount while retaining trial and recurring amounts on the same price. Cardless trials let customers begin without a payment method. Subscription checkout requires explicit consent before saving a payment method. California customers see confirmation for later recurring charges. South Korean subscriptions expose renewal-consent state through `consent_requirements` in API and webhook data. ### Portal and cancellation Customer portal sessions produce authenticated links that automatically log a customer in. Legacy subscription management-link responses now return customer portal links. Cancellation Flows can run within the portal as the subscription offboarding experience. ## Checkout quick reference ### Checkout modes Express checkout prioritizes Apple Pay on mobile and Google Pay on Android and Chrome. Early-access post-purchase upsell checkout supports reduced-friction one-click purchases. Automated abandoned-checkout emails may include an optional recovery discount. Hosted checkout can use branded custom subdomains as an early-access feature. Four API operations list and inspect approved checkout domains and trigger Apple Pay verification. ### Open-checkout updates and errors Paddle.js can update items, discounts, customer information, and custom data on an open checkout. Checkout events distinguish invalid or missing input from payment errors such as no valid payment method, allowing separate frontend fallback handling. ### Previews and method selection Price previews return localized, formatted prices with tax and discount calculations. Paddle.js can preview complete transaction totals without a server call. Preview responses can report valid payment methods, and checkout can be restricted to a selected set. ## Pricing, tax, and catalog quick reference A transaction may receive a one-off discount object without a catalog discount. Discount groups organize catalog discounts and can be fetched, renamed, or archived through the API. Discount codes are case-insensitive. For partial refunds, setting `tax_mode` allows tax-exclusive amounts so Paddle can calculate tax. Adjustment webhooks include `tax_rates_used`, grouping subtotal, tax, and total by rate. Transaction totals expose tax charged after credits. Transactions and one-time subscription charges may use inline product or price attributes without catalog entries. Recurring non-catalog items may be added when updating a subscription. Subscription items preserve complete price and product snapshots from when each item was added. ## Reporting and operational quick reference Paddle offers subscriptions, checkouts, balance, catalog, and transaction or adjustment line-item reports, along with seven API operations for account time-series metrics. Reports can be created and downloaded through the API, and webhooks are available for report workflows. Payout reconciliation reports connect payouts to transaction-linked sales, tax, fee, and foreign-exchange movements. They can be filtered by payout period and movement category. Report creation is limited to 100 per day; price and transaction preview operations allow 1,000 requests per minute per IP address. ## Applying the patch 1. Identify the integration surface involved. 2. Open every indexed reference that matches that surface. 3. Apply the specific compatibility rules and limits from those references. 4. Preserve distinctions between live and sandbox, account and destination defaults, payment and completion, recurring and one-time behavior, and stable and early-access features.