Sync Paddle subscription state into your database

When to use this skill

Use this skill when you need a local copy of Paddle subscription and customer state — typically to gate features by subscription status, render account pages without round-tripping to the Paddle API, and report on revenue. This skill defines the table schema, the events to subscribe to, the upsert pattern, how to map your app's users to Paddle customers, status semantics, and how to handle scheduled changes (pauses, cancels effective at end of period).

This skill assumes you already receive verified webhooks. If you don't, do webhooks first — that skill covers the route handler and signature verification. The code here lives inside the event handler functions that skill creates.

Prerequisites

• Working webhook endpoint with signature verification (webhooks).
• A database (the examples use Supabase, but any SQL store with UPSERT works).
• Subscribed events on your notification destination:
  • customer.created, customer.updated
  • subscription.created, subscription.updated, subscription.canceled
  • Optionally: transaction.completed (for one-off purchases), subscription.activated (when a trial converts)

Why mirror state at all?