Skip to main content

Paddle

Paddle is a Merchant of Record (MoR) — Paddle handles tax collection, compliance, and VAT/GST remittance globally. Subscribd integrates with Paddle Billing (the modern API, not Paddle Classic).

Configuration

Environment variables

Set PADDLE_SANDBOX=true to use the Paddle sandbox environment.

Webhook-activation flow

Paddle uses a webhook-activation model. CreateSubscription returns an Incomplete subscription with a checkout_url in meta:
The user completes payment on Paddle’s checkout page. Paddle then sends a webhook confirming the subscription, at which point Subscribd transitions the subscription to Active and fires SubscriptionCreated. The event is not fired from CreateSubscription.

Webhooks

Register https://yourapp.com/subscribd/webhook/paddle as a notification destination in the Paddle Dashboard. Enable:
  • subscription.created
  • subscription.updated
  • subscription.canceled
  • subscription.paused
  • subscription.resumed
  • transaction.completed
  • transaction.payment_failed
Copy the Secret key from the notification settings and set it as PADDLE_WEBHOOK_SECRET.

Limitations

  • Proration is handled by Subscribd’s built-in ProrationEngine.
  • Trial extension is not supported natively. ExtendTrial updates the local trial_ends_at only.

Next steps