Skill: ivangdavila/paddle (version 1.0.0)

--- name: Paddle slug: paddle version: 1.0.0 homepage: https://clawic.com/skills/paddle description: Integrate Paddle payments with subscriptions, webhooks, checkout, and tax compliance. changelog: Initial release with API reference, webhook handling, and checkout integration. metadata: {"clawdbot":{"emoji":"🏓","requires":{"bins":[]},"os":["linux","darwin","win32"]}} --- ## 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. ``` ~/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`

path: memory-template.md
content: # Memory Template — Paddle

Create `~/paddle/memory.md` with this structure:

```markdown
# Paddle Memory

## Status
status: ongoing
version: 1.0.0
last: YYYY-MM-DD
integration: pending | done | declined

## Environment
<!-- sandbox | production | both -->

## Product
<!-- Their product type, pricing model, trial setup -->

## Tech Stack
<!-- Languages, frameworks, hosting for integration recommendations -->

## Price IDs
<!-- Map of their prices for reference -->
<!-- Example: basic_monthly: pri_xxx, pro_annual: pri_yyy -->

## Notes
<!-- Specific requirements, edge cases, decisions made -->

---
*Updated: YYYY-MM-DD*
```

## Status Values

| Value | Meaning | Behavior |
|-------|---------|----------|
| `ongoing` | Still learning their setup | Gather context opportunistically |
| `complete` | Has enough context | Work normally |
| `paused` | User said "not now" | Don't ask, work with what you have |
| `never_ask` | User said stop | Never ask for more context |

## Key Principles

- **No config keys visible** — use natural language descriptions
- **Learn from behavior** — observe their code, don't interrogate
- **Most integrations stay `ongoing`** — always learning new edge cases
- Update `last` on each use


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)