━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PADDLE SUBSCRIPTIONS & PAYMENTS PLUGIN
Getting Started Guide
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

BEFORE YOU START — GET YOUR PADDLE CREDENTIALS
───────────────────────────────────────────────
1. Create a free Paddle account at paddle.com
2. In the Paddle dashboard, go to:
  Developer Tools → Authentication
3. Switch to SANDBOX environment (top of page)
4. Click "Generate API Key" — name it "Bubble Plugin"
5. Copy the key (starts with sdbx_ for sandbox)
6. When ready to go live, repeat for LIVE environment
  (live keys start with live_)

IMPORTANT: Sandbox and live are completely separate.
Test everything in sandbox first before using live keys.

CREATE YOUR PRODUCTS & PRICES IN PADDLE
───────────────────────────────────────────────
Before creating any payment or subscription, you need
a Price ID from Paddle:

1. Paddle dashboard → Catalog → Products → New Product
2. Add a Price: set amount, currency, billing type
  - One-time: for regular payments (SSAs 01-04)
  - Monthly/Yearly: for subscriptions (SSAs 05-11)
3. Copy the Price ID (looks like: pri_01abc123...)

You'll use this Price ID in the items_json field.
Example: [{"price_id":"pri_01abc123","quantity":1}]

THE 14 SERVER-SIDE ACTIONS — QUICK REFERENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

── REGULAR PAYMENTS (One-Time) ──
01 — Create Transaction      Start a payment, get checkout_url
02 — Get Transaction         Check payment status & totals
03 — List Transactions       Get payment history for a customer
04 — Get Transaction Invoice Get PDF invoice URL

── SUBSCRIPTIONS ──
05 — Get Subscription        View subscription details & URLs
06 — List Subscriptions      Get all subs for a customer
07 — Cancel Subscription     End a subscription
08 — Pause Subscription      Temporarily stop billing
09 — Resume Subscription     Restart a paused subscription
10 — Create One-Time Charge  Bill extra amount to subscriber
11 — Update Subscription     Change plan (upgrade/downgrade)

── WEBHOOKS ──
12 — Verify Webhook Signature  Confirm request is from Paddle
13 — Parse Subscription Webhook  Extract subscription data
14 — Parse Transaction Webhook   Extract payment data

EVERY ACTION REQUIRES THESE TWO FIELDS:
• api_key     — Your Paddle API key (sdbx_ or live_)
• environment — Type "sandbox" or "live"

QUICK START: ONE-TIME PAYMENT FLOW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: User clicks "Buy Now" button
Step 2: Workflow → Plugin Action → 01 — Create Transaction
       Set items_json: [{"price_id":"YOUR_PRICE_ID","quantity":1}]
       Set customer_email: Current User's email
       Set custom_data: {"bubble_user_id":"Current User's unique id"}
Step 3: Open external website → URL = Create Transaction's checkout_url
Step 4: User pays on Paddle's page
Step 5: Paddle fires transaction.completed webhook to your endpoint
Step 6: Webhook workflow → 12 — Verify Webhook Signature
Step 7: If is_valid = "true" → 14 — Parse Transaction Webhook
Step 8: Grant user access in your database

QUICK START: SUBSCRIPTION FLOW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: Create a RECURRING price in Paddle (monthly/yearly)
Step 2: Same as one-time payment — use 01 — Create Transaction
       with the recurring Price ID
Step 3: User pays → Paddle creates subscription automatically
Step 4: Paddle fires subscription.created webhook
Step 5: Webhook workflow → 12 — Verify Webhook Signature
Step 6: If is_valid = "true" → 13 — Parse Subscription Webhook
Step 7: Save to your Bubble User database:
       - subscription_id (sub_xxx)
       - customer_id (ctm_xxx)
       - status ("active")
       - next_billed_at
       - cancel_url
       - update_payment_url

SETTING UP WEBHOOKS IN BUBBLE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Bubble → Settings → API → enable "Expose as API endpoint"
2. Backend Workflows → New API Workflow
  Name: paddle-webhook | Method: POST
3. Copy the endpoint URL Bubble gives you
4. Paddle Dashboard → Developer Tools → Notifications
  → New Notification → paste your Bubble URL
5. Select events: transaction.completed,
  subscription.created, subscription.updated,
  subscription.canceled, transaction.payment_failed
6. Copy the SECRET KEY shown (different from API key!)
7. Use this secret in 12 — Verify Webhook Signature

SANDBOX TEST CARD (no real money)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Card: 4242 4242 4242 4242
Expiry: Any future date  |  CVV: Any 3 digits

NEED HELP?
━━━━━━━━━━
• Paddle API docs: developer.paddle.com
• Paddle sandbox dashboard: sandbox-vendors.paddle.com
• Bubble plugin docs: manual.bubble.io/account-and-marketplace/building-plugins