Paddle

Integrate Paddle payments with subscriptions, webhooks, checkout, and tax compliance.

Setup

On first use, read setup.md for integration guidelines.

When to Use

User needs to integrate Paddle for SaaS payments. Agent handles API calls, webhook verification, checkout setup, subscription management, and tax compliance configuration.

Architecture

Memory lives in ~/paddle/. See memory-template.md for structure.

text

~/paddle/
├── memory.md     # API keys, environment, product IDs
└── webhooks.md   # Webhook endpoints and event handling

Quick Reference

Topic	File
Setup process	setup.md
Memory template	memory-template.md
API endpoints	api.md
Webhook handling	webhooks.md

Core Rules

1. Always Use Sandbox First

• Test ALL integrations in sandbox before production
• Sandbox API: https://sandbox-api.paddle.com
• Production API: https://api.paddle.com
• Never skip sandbox testing for payment flows

2. Verify Webhook Signatures

• Every webhook MUST be verified before processing
• Use the webhook secret from Paddle dashboard
• Reject requests with invalid signatures immediately
• Log failed verifications for debugging

3. Handle Subscription States Correctly

State	Meaning	Action
active	Paying customer	Grant access
trialing	In trial period	Grant access, remind before end
past_due	Payment failed	Retry period, warn user
paused	User paused	Restrict access, allow resume
canceled	Subscription ended	Revoke access at period end

4. Store Paddle IDs Correctly

• customer_id (ctm_xxx) — unique per customer
• subscription_id (sub_xxx) — unique per subscription
• transaction_id (txn_xxx) — unique per payment
• price_id (pri_xxx) — your pricing configuration
• Map these to your internal user/subscription records

5. Use Paddle Retain for Dunning

• Enable Paddle Retain in dashboard for failed payments
• It handles retry logic and customer communication
• Track subscription.past_due events but let Paddle retry first
• Only take action after subscription.canceled from failed payments

Common Traps

• Hardcoding price IDs → Use environment variables, prices change between sandbox/production
• Processing webhooks without verification → Security vulnerability, anyone can fake events
• Ignoring past_due state → User loses access during retry window, bad UX
• Not handling proration → Confusing charges when users upgrade/downgrade mid-cycle
• Testing with production keys → Real charges, angry customers, refund headaches

External Endpoints

Endpoint	Data Sent	Purpose
https://api.paddle.com	Customer data, subscription info	Payment processing
https://sandbox-api.paddle.com	Test customer data	Sandbox testing

No other data is sent externally.

Security & Privacy

Data that leaves your machine:

• Customer email and name sent to Paddle for billing
• Payment amounts and subscription details
• IP addresses for tax calculation

Data that stays local:

• API keys stored in environment variables
• Webhook secrets never logged
• Internal user mappings

This skill does NOT:

• Store credit card numbers (Paddle handles PCI compliance)
• Access payment methods directly
• Share customer data with third parties beyond Paddle

Trust

By using this skill, customer and payment data is sent to Paddle. Only install if you trust Paddle with your billing data.

Related Skills

Install with clawhub install <slug> if user confirms:

• billing — General billing patterns
• payments — Payment processing
• subscriptions — Subscription management

Feedback

• If useful: clawhub star paddle
• Stay updated: clawhub sync