Subscriptions — recurring billing
The Subscription component adds a pricing table of recurring plans to any
page. Define your plans (price, billing period, optional free trial); visitors pick one and subscribe, and the gateway
bills them on schedule. The plans are stored and seeded for you, every subscriber is tracked in a
pp_subscriptions table, and renewals and cancellations are handled automatically via
webhooks plus a self-service manage page. It builds on the Payment gateways, so it reuses
the same keys.
Contents
- How it works
- Defining plans
- Which gateways
- Tables & records
- Renewals, cancellation & webhooks
- Every property
How it works
- The visitor picks a plan and clicks Subscribe. The button sends only the component id + plan code — never the price — so the amount can't be changed from the browser.
- Your server creates the subscription with the gateway and sends the visitor to its hosted page to authorise it.
- On return the server confirms the subscription is active and records it. The subscriber sees a receipt with a manage / cancel link (also emailed).
- Each renewal, payment failure, or cancellation reaches your app as a webhook and updates the subscription's status and next-billing date automatically.
Defining plans
Add one or more plans in the inspector. Each plan has a code (a stable id like pro), a
name, an amount, a billing period (day/week/month/year) with an every-N multiplier, an optional
free trial in days, a Popular highlight, and a features list (one per line). Plans are
seeded into pp_subscription_plans the first time the page renders, so you always have a
plans table to build reports on.
Which gateways
| Gateway | Recurring? |
|---|---|
| Test | Simulated recurring — no keys, no real money. Full subscribe → active → cancel flow for building + demos. |
| Manual | Records an offline recurring pledge you manage by hand. |
| Stripe | Yes — Stripe Checkout in subscription mode (test with an sk_test_ key). |
| PayPal | Yes — PayPal Subscriptions (product + plan). Set mode to sandbox to test. |
| Razorpay | Yes — Razorpay Subscriptions (INR). Test with an rzp_test_ key. |
Tables & records
Two tables are created automatically (MySQL, MariaDB, PostgreSQL, SQLite, SQL Server):
pp_subscription_plans— your plans, seeded from the component (code, name, amount, interval, trial).pp_subscriptions— one row per subscriber: reference, plan, gateway, status (pending / active / past_due / canceled), the gateway's subscription id, and the current-period end.
Build a List page on either table to manage plans and subscribers.
Renewals, cancellation & webhooks
- Renewals happen on the gateway and are reported to your app by webhook — point the gateway's
webhook at
…/api/sub-webhook.php?gateway=<name>. Each successful charge extends the period; a failed charge marks the subscription past due. - Cancellation — the subscriber's receipt/manage page has a Cancel subscription button
(confirmed by their email), which cancels at the gateway and stops future billing. You can also cancel from the
pp_subscriptionslist.
Every property
| Property | What it does |
|---|---|
| Title / Subtitle | The pricing-table heading. |
| Gateway | Which gateway bills the subscriptions (keys from Settings → Payments). |
| Default currency | Used for plans that don't set their own (Razorpay requires INR). |
| Ask for email | Collect the subscriber's email up front so confirmations + the manage link work. |
| Plans | Code, name, amount, currency, billing period + every-N, free-trial days, “Popular” highlight, features. |
| Button label / Align | The Subscribe button text and the widget alignment. |