Paddle Billing

Pathrule3 Rules • 2 Memories • 1 Skill

Paddle acts as Merchant of Record, but the application still owns the product access and operational state derived from its billing events. This bundle separates transactions, payments, and subscriptions, handles at-least-once and out-of-order webhook delivery, preserves proration intent, and reconciles local access against Paddle. Unlike Stripe Billing, it follows Paddle's transaction-centered lifecycle and hosted customer-management model.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

webhooks/

paddle/

Process Paddle webhooks idempotently and by occurrence time

access/

Grant access from verified billing evidence

billing/

paddle/

State proration intent on every subscription item change

Transactions, payments, and subscriptions answer different questions

Customer management URLs are temporary capabilities

reconcile-paddle-access

Rules

Process Paddle webhooks idempotently and by occurrence time/src/webhooks/paddlehighstrictEvery event is authenticated, deduplicated by event id, and applied only when it is newer than the local projection.

1	Paddle webhook delivery is at least once and related events can arrive out of order, so receipt order cannot define billing truth. Authenticate the raw request before parsing, persist the event id and occurred_at value, and make the projection update conditional on the incoming evidence being newer than the state already applied.
2
3	- Acknowledge quickly after durable capture and move business processing to a retryable worker.
4	- Deduplicate by Paddle event_id and keep successful replays as no-ops with an auditable receipt.
5	- Compare occurred_at or a stronger entity version before changing subscription, transaction, or access state.
6	- Quarantine unrecognized event shapes and repeated failures instead of returning success while dropping them.
7
8	Verification: Deliver duplicates and reverse the order of paid, subscription-created, and completed events; confirm one durable receipt per event and the same final projection.

Grant access from verified billing evidence/src/accesshighstrictCheckout redirects improve user experience, but only verified Paddle state can create or revoke durable product access.

1	A browser success page is user-controlled navigation, not durable payment evidence. Create access only from authenticated Paddle events or an explicit server-side Paddle lookup, then store the provider ids and evidence that caused each transition. Keep access projection separate from the raw billing objects so temporary delivery gaps do not erase history.
2
3	- Map each price or product to an internal entitlement set through versioned configuration.
4	- Record the Paddle customer, transaction, subscription, event, and occurrence time behind every access change.
5	- Define grace, past-due, canceled, paused, and resumed behavior as explicit transitions rather than scattered status checks.
6	- Make repeated grants and revocations idempotent and preserve the previous state for audit.
7
8	Verification: Skip the return page, replay the webhook, delay subscription creation, and restore a paused subscription; confirm access converges from verified evidence alone.

State proration intent on every subscription item change/src/billing/paddlehighstrictA subscription item update names its proration billing mode and expected commercial effect before it reaches Paddle.

1	Changing Paddle subscription items can alter what is charged now, deferred, credited, or left unchanged. Never let a generic update helper choose that commercial decision implicitly. The application command must name the proration billing mode, expected effective time, actor, reason, and preview accepted by the customer or operator.
2
3	- Validate that the requested price, quantity, currency, and billing interval are compatible before calling Paddle.
4	- Present or log the previewed immediate charge, credit, and next recurring total before confirmation.
5	- Use one idempotent internal change intent and reconcile ambiguous provider responses by subscription lookup.
6	- Persist the requested and resulting item sets so support can explain a later invoice.
7
8	Verification: Exercise upgrade, downgrade, quantity change, interval change, retry after timeout, and no-proration cases; confirm the result matches the named mode.

Memories

Transactions, payments, and subscriptions answer different questions/src/billing/paddleA Paddle transaction is the commercial record, payments are collection attempts, and a subscription governs recurring lifecycle.

1	Do not compress Paddle transactions, payments, and subscriptions into a single local status. A transaction describes priced commercial items and its billing lifecycle, a payment describes an attempt to collect money for that transaction, and a subscription describes the recurring relationship that can produce later transactions. Financial records are preserved and post-billing changes are represented through adjustments rather than deletion.
2
3	Keep the three provider identifiers on separate local records and link them to the same internal account and order context. Decide which object is authoritative for each question: transaction for the amount and completion evidence, payment for attempt diagnostics, and subscription for renewal or item state. See /src/access for the derived product-access projection and /src/webhooks/paddle for ordering rules.

Customer management URLs are temporary capabilities/src/billing/paddlePaddle management URLs are generated when needed and returned directly to an authorized user instead of stored as durable account data.

1	Paddle customer and subscription management URLs are temporary capabilities. Caching one in a user profile, database row, support note, or analytics event turns a short-lived delegated action into a stale or leaked link. Generate the appropriate URL on demand after authenticating the user and authorizing access to the internal account connected to the Paddle customer.
2
3	Return the link only through the requesting secure session, avoid logging the full value, and let expiration require a fresh request. Never accept a customer or subscription id from the client without resolving it through the server-owned account mapping. If a custom management action exists, keep the same authorization and audit boundary. See /src/access for ownership checks that precede link generation.

Skills

reconcile-paddle-access/src/billing/paddleCompare Paddle customers, transactions, subscriptions, and adjustments with the local access projection and repair explainable drift.

1	---
2	name: reconcile-paddle-access
3	description: Compare Paddle billing records with the local access projection and repair explainable drift.
4	---
5
6	# Reconcile Paddle Access
7
8	1. Select a bounded account or time window and export local Paddle ids, event receipts, subscription snapshots, transaction states, adjustments, and access transitions.
9	2. Fetch the current Paddle customer, subscription, and relevant transactions; preserve raw evidence and retrieval time without overwriting prior snapshots.
10	3. Classify differences as delayed delivery, out-of-order application, missing mapping, manual provider change, configuration drift, or unsupported state.
11	4. Replay the smallest verified event or run an explicit idempotent repair command; never edit access without linking the provider evidence and reason.
12	5. Re-run the comparison and record counts, unresolved cases, owner, and next review time.
13
14	A successful run proves that the same provider facts produce the same local access state and that every repair can be explained from retained evidence.

Why this pattern

Agents grant access from a checkout return, assume Paddle events arrive once and in order, or collapse transactions, payments, and subscriptions into one mutable status.

Built for SaaS teams using Paddle for recurring billing, checkout, invoicing, and customer self-service.

Keeps your assistant from:

Granting durable access from an unverified browser redirect
Older webhook events overwriting a newer subscription state
Caching temporary customer portal URLs as permanent links

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25