> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Subscriptions
> Set up recurring revenue with subscription and membership products in Pocketsflow.
Subscriptions turn one-time buyers into recurring customers. This is the most
detailed guide in the Selling section: it covers how recurring billing works,
how to build a subscription, the public page and checkout, the subscriber
lifecycle and every status, the customer portal, renewals, failed payments, and
the webhooks a subscription fires along the way.
Subscription billing is powered by our payment infrastructure.
It stores the card on file, runs the renewal schedule, retries failed charges,
and hosts the billing portal. Pocketsflow configures all of it for you and keeps
your dashboard, orders, and webhooks in sync — you never log into the payment provider.
## When to use subscriptions
Subscriptions are a good fit when:
* You deliver **ongoing value** — a community, regular content drops, office
hours, a tool, or a members-only feed.
* You want **predictable recurring revenue** instead of one-off spikes.
* You're comfortable managing renewals, trials, and cancellations.
If your product delivers its value in a single download or a one-time course with
lifetime access, a [one-time product](/selling/product-types) is simpler — no
renewals, trials, or dunning to manage.
**Subscription vs. product at a glance.** A product is bought once and accessed
forever. A subscription bills on a repeating schedule, tracks each subscriber's
status over time, can offer a free trial, and gives buyers a self-service portal
to manage or cancel. They're separate objects in Pocketsflow with separate
dashboard sections.
## How recurring billing works
When someone subscribes:
1. Our payment infrastructure collects the first payment (or, with a trial, authorizes the card and
defers the charge).
2. Pocketsflow creates a **subscriber** record with a live status and grants
access.
3. At the end of each billing period, our payment infrastructure automatically charges the saved card
again.
4. Each successful charge is recorded as a new **order** in your dashboard,
tagged as an `initial` or `renewal` payment, so recurring revenue appears
alongside one-time sales.
5. If a charge fails, the subscriber moves to `past_due` and our payment infrastructure retries.
6. The customer can cancel or manage their plan at any time from the portal.
Billing is **automatic and open-ended** — there's no fixed end date. It continues
until the customer cancels, you cancel on their behalf, or repeated payment
failures end it.
## Billing frequency
Every subscription bills on one of three frequencies:
| Frequency | Charges the customer | Typical use |
| ----------- | -------------------- | ------------------------------------------------------------ |
| **Weekly** | Every 7 days | High-cadence content, signal groups, fast-moving communities |
| **Monthly** | Every month | The default — memberships, tools, most communities |
| **Yearly** | Every 12 months | Discounted annual plans, "commit for a year" offers |
**Monthly** is the default. Choose the frequency in the **Trial & frequency**
section of the subscription editor. A common pattern is to publish **two
subscriptions** for the same offer — a monthly plan and a discounted yearly plan
— and let buyers choose.
Price the yearly plan at roughly 10 months' worth of the monthly price. It rewards
the annual commitment, improves cash flow, and reduces churn because subscribers
renew once a year instead of twelve times.
## Free trials
A subscription can start with a **free trial** measured in days. Set the trial
length in the **Trial & frequency** section (`0` = no trial).
* During the trial the customer has **full access** but is **not charged**.
* When the trial ends, our payment infrastructure charges the card on file automatically and the
subscriber moves from `trialing` to `active`.
* If the customer cancels before the trial ends, they're never charged.
A trial still collects a valid payment method up front. That deliberately filters
out low-intent signups and means the conversion to a paid renewal is automatic —
you don't have to chase anyone for a card when the trial lapses.
Common trial lengths: **7 days** (most common), **14 days** (higher-consideration
offers), or **3 days** (fast-value tools). Always state the trial length and the
price that follows it clearly on your page and checkout.
## Creating a subscription
The subscription editor is a short, four-step wizard. You can revisit any step
before or after publishing.
Set the core details and what subscribers receive:
* **Name** and **short description** (subtitle).
* **What subscribers get** — either a **file** to download, a **URL** to send
them to (for example a Discord invite, a course platform, or a members
area), or a **callback URL** that receives the subscription and customer
IDs so your own system can grant access.
* **Price** per billing period, in your account currency.
* **Free trial** length in days, and the **billing frequency** (weekly /
monthly / yearly).
* An optional **thumbnail** (recommended 1280×720, 16:9).
Decide whether the subscription shows a **public product page** before
checkout, and if so choose its layout, colors, typography, and which sections
appear. This reuses the exact same nine-layout page system as one-time
products — see [Page templates](/selling/page-templates). If you turn the
product page off, buyers go **straight to the embedded checkout**.
Pick a checkout skin (template) and palette. This is the same checkout
template system used by products — see [Checkout page](/selling/checkout-page).
You can also require the buyer's **first name** and/or **last name** here (the
payment form always collects email).
Set up post-purchase behavior in the **Portal** step:
* **Redirect URL** (required) — where buyers land after subscribing.
* **Portal text** (`portalText`) — the headline shown at the top of the
buyer's native subscriber portal (see [The customer portal](#the-customer-portal)).
* **Privacy policy** and **terms of service** links.
* Optionally, the **callback URL** pattern used to notify your own system.
The Portal step also displays this subscription's **ID** and the portal-link
template so you can build links yourself if you need to.
Once you publish, the subscription gets its own shareable link and can be added to
your [Link in bio](/selling/creator-page).
Make sure your page and checkout copy clearly communicate that this is a
**recurring charge**, the **amount**, the **frequency**, and any **trial**. Clear
disclosure reduces refund requests, chargebacks, and support tickets.
## The public subscription page
If you enable a product page, the subscription renders it using the same public
page renderer as one-time products, so all nine layouts, the typography and
corner tokens, background patterns, reviews, and sales-count social proof are
available. See [Page templates](/selling/page-templates) for the layout catalog.
* The primary call-to-action (its label is configurable, e.g. "Subscribe for
\$19/mo") sends the visitor to the shared **embedded checkout** with the
subscription attached.
* If you **don't** enable a product page, the subscription link takes visitors
**directly to checkout** — ideal when you drive traffic from a landing page or
ad you've already written the pitch on.
* Reviews and the live subscriber/sales count can be shown or hidden per
subscription.
The subscription page lives at a dedicated URL so it never collides with your
product storefront links.
## The embedded checkout
Subscriptions use the same checkout as products, including the **embeddable**
mode. You can drop the checkout straight onto your own website. When embedded, the
checkout communicates with the parent page using `postMessage`:
* A `processing` message fires as soon as payment starts.
* A single `success` message fires once the order is confirmed, carrying the
order details — so your site can show its own confirmation, unlock content, or
fire analytics.
* A `resize` message keeps the iframe sized to its content.
Because the frame stays loaded after payment, embedded subscription checkouts wait
for the order to be confirmed on the backend before signalling success. Details
and copy-paste embed snippets are in [Checkout page](/selling/checkout-page).
## The subscriber lifecycle
Every person who subscribes gets a **subscriber** record (one per subscription
they join). It stores their email, name, live status, test-mode flag, and a link
to their personal billing portal. Its **status** is the single source of truth for
where they are in the billing lifecycle.
```text theme={null}
subscribe
│
(trial?) ───┼─── no trial
│ │ │
trialing │ active ◀────── renewal succeeds
│ │ │ ▲
trial ends ───┘ │ └── retry succeeds
│ │
└────▶ active past_due ◀── renewal charge fails
│ │
cancel / │ └── retries exhausted
lapse ▼ ▼
canceled unpaid / canceled
```
### Status reference
| Status | What it means | How a subscriber gets here |
| ----------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| `trialing` | In a free trial; full access, not yet charged | Subscribed to a plan with a trial |
| `active` | Paid and in good standing | First payment succeeded, or a trial converted, or a renewal succeeded |
| `past_due` | A renewal charge failed; automatic retries in progress | A `payment.failed` on a renewal |
| `paused` | Temporarily suspended, not billing | Paused (where supported) |
| `canceled` | Ended; access revoked at the appropriate time | Customer or you canceled, or retries were exhausted |
| `unpaid` | Charges failed past the retry window | Dunning exhausted |
| `incomplete` / `incomplete_expired` | The first payment never completed | Checkout started but the initial charge didn't settle |
| `succeeded` / `refunded` | Payment settled / a charge was refunded | Payment or refund events |
When a new subscriber activates, Pocketsflow emails **both** the subscriber (an
"activated" email with a link to their portal) and **you** (a "new subscription"
notification). No manual step is required to grant access.
## Managing subscribers from the dashboard
In the **Subscriptions** area you can:
* See every subscriber for a plan and their current **status**.
* Distinguish **active**, **past-due**, and **canceled** subscribers at a glance.
* View each subscriber's **payment history** — every renewal is a dated order.
* Identify which subscription each subscriber is tied to and when they joined.
* Open a subscriber's **portal link** to help them with billing changes.
* Cancel a subscription on a customer's behalf.
Because each successful charge is recorded as an order, your **Orders** page and
[Analytics](/operations/analytics) show subscription revenue next to one-time
sales, including the split between initial and renewal payments.
## Renewals
At the end of each billing period our payment infrastructure charges the saved card automatically:
* **On success**, Pocketsflow records a new order tagged `renewal`, keeps the
subscriber `active`, and fires the `invoice.payment_succeeded` webhook.
* **On failure**, the subscriber moves to `past_due`, our payment infrastructure retries on its dunning
schedule, and Pocketsflow fires `invoice.payment_failed`.
Renewals are idempotent: if our payment infrastructure re-delivers the same payment event, Pocketsflow
records the order only once, so you never see duplicate renewal charges in your
dashboard.
## The customer portal
Every subscriber gets a **native, branded self-service portal** — hosted on your
Pocketsflow subdomain, not a plain third-party redirect. From it a customer can
see where their subscription stands, review every charge, cancel, resume, and
update the card on file, all without emailing you.
What a subscriber sees and does in the portal:
* **A headline you write** — the `portalText` from the Portal step is shown at
the top of the page (for example, "Manage your Pro membership below").
* **Subscription details and live status** — plan, price, billing frequency,
next billing date, and the current subscription status (`active`, `trialing`,
`past_due`, `paused`, or `canceled`).
* **Full payment history** — the initial charge plus every renewal, each with a
receipt.
* **Cancel** — schedules the subscription to end at the period end
(cancel-at-period-end), so the buyer keeps access through the period they've
paid for.
* **Resume** — undoes a pending cancellation while the paid period is still
running, returning the subscription to `active`.
* **Manage / Update payment method** — hands off to **the secure payment
page** to change the card on file. Card details are entered on the secure payment page, never
stored by you.
### How the portal link is structured
The portal link follows this pattern, on your account's subdomain:
```text theme={null}
https://yourhandle.pocketsflow.com/portal/{subscriptionId}/{subscriptionCustomerId}
```
* `subscriptionId` is the subscription's `id`.
* `subscriptionCustomerId` is that subscriber's `subscriptionCustomer.id`.
The link is included in the activation email automatically, so subscribers always
have a way in, and it's also reachable from a buyer's **Purchases** page.
A portal link needs **both** the subscription ID **and** that customer's
subscriber ID. A link that's missing one, or that still contains the literal
`{subscriptionId}` / `{subscriptionCustomerId}` placeholders, will show an
"invalid link" error rather than opening. If you build portal links yourself
(for example in your own app or emails), substitute both real IDs.
### Portal text and redirects
In the Portal step of the editor you control:
* **Portal text** (`portalText`) — the headline shown at the top of the buyer's
native portal.
* **Redirect URL** — where a buyer lands after subscribing (required).
* **Privacy policy** and **terms of service** links surfaced during the flow.
If you use a **callback URL**, Pocketsflow appends the subscription and customer
IDs to it so your own backend can grant or revoke access, for example:
```text theme={null}
https://yoursite.com/grant-access?subscriptionId={id}&subscriptionCustomer={subCId}&redirect_status=succeeded
```
Store both IDs in your database when the callback fires — you'll need the
subscriber ID to match future webhook events to the right user.
## Cancel, pause, and resume
Make your cancellation policy explicit on your page, checkout, and portal:
* **Where** customers cancel — usually the self-service portal, or by contacting
you.
* **When** it takes effect — our payment infrastructure supports **cancel at period end** (the customer
keeps access until the paid period runs out) as well as immediate cancellation.
A cancel-at-period-end change fires the `customer.subscription.updated` webhook
so your systems can react without cutting access early.
* **Refunds** — decide whether you refund the most recent renewal on cancellation.
When a subscription actually ends (immediately or at period end), the subscriber
becomes `canceled`, access is revoked, and the `customer.subscription.deleted`
webhook fires.
## Failed payments and dunning
When a renewal payment fails:
1. The subscriber moves to **`past_due`** and `invoice.payment_failed` fires.
2. Our payment infrastructure **retries** the charge automatically on its dunning schedule.
3. If a retry succeeds, the subscriber returns to `active` and a renewal order is
recorded.
4. If retries are exhausted, the subscription ends and the subscriber becomes
`canceled` / `unpaid`.
Best practices:
* Turn on notifications for failed payments so you can nudge high-value customers.
* Point past-due customers to their **portal** to update the card on file.
* Decide up front how long you'll keep access on while a payment is failing, and
state it in your terms.
## Upgrades, downgrades, and plan changes
If you offer multiple plans (for example monthly and yearly, or tiers):
* Give subscribers a clear path to switch plans.
* Decide whether a change takes effect **immediately** or at the **next billing
date**, and whether you **prorate**.
* Communicate exactly how price and access change when switching.
Document any special rules (proration, mid-cycle credits) on your pricing and FAQ
sections so there are no surprises.
## Webhooks for subscriptions
If you consume webhooks, subscription events can drive access control in external
systems and notifications in your own tools (Slack, a CRM, a Discord bot). The
events a subscription's lifecycle fires:
| Event | Fires when | Use it to |
| ------------------------------- | ------------------------------------------------ | ----------------------------------------------- |
| `payment_intent.succeeded` | A subscriber first activates | Grant access, welcome the member |
| `invoice.payment_succeeded` | A **renewal** payment succeeds | Extend access for another period |
| `invoice.payment_failed` | A renewal charge fails (subscriber → `past_due`) | Warn the customer, start your own dunning |
| `customer.subscription.updated` | Cancel-at-period-end is toggled | Schedule end-of-access without cutting it early |
| `customer.subscription.deleted` | A subscription ends / is canceled | Revoke access |
Each webhook payload includes the `subscription` (with its `id` and the
subscriber's `customerId`) and the `customer` (email, first and last name). Use
the subscriber `customerId` you stored at activation to match every later event
to the right person. Webhooks fire in **test mode** for test subscriptions and
**live** for real ones.
For payload shapes, delivery, retries, and signature verification, see
[Webhook events](/api-webhooks/events) and
[Consuming webhooks](/api-webhooks/consuming-webhooks).
## Testing a subscription end-to-end
Before you send real traffic:
Create the subscription in test mode so no real money moves.
Open the checkout in a private window and subscribe. Confirm you (and the test
buyer) receive the activation emails and that the redirect works.
Confirm a subscriber appears with status `active` (or `trialing`) and that a
first order was recorded.
Follow the portal link from the activation email and confirm it opens the
billing portal rather than an error.
Confirm your endpoint received `payment_intent.succeeded`, and later
`invoice.payment_succeeded` on renewal.
Then switch to live and repeat a quick smoke test with a real card and a real
(small) charge you refund afterwards.
## Frequently asked questions
A single subscription has one frequency and price. To offer monthly **and**
yearly, publish two subscriptions for the same offer and let buyers pick. It
keeps each plan's billing, trials, and reporting clean.
Trial subscribers get full access immediately and are billed automatically
when the trial ends. If they cancel before then, they're never charged.
Access is revoked when the subscription ends. If you gate access in your own
system via a callback or webhook, act on `customer.subscription.deleted`
(immediate) or schedule end-of-access from `customer.subscription.updated`
(cancel at period end).
Yes. Every successful charge — initial and renewal — is recorded as an order
and appears in your dashboard and analytics, so you can see MRR-style recurring
revenue next to one-time sales.
Yes — that's what the customer portal is for. Point past-due customers there to
fix a failed payment without your involvement.
## What's next
* To increase revenue per customer, set up [Upsells & bundles](/selling/upsells-and-bundles).
* To design the subscription's page, see [Page templates](/selling/page-templates).
* To skin its checkout, see [Checkout page](/selling/checkout-page).
* To monitor performance, explore [Analytics](/operations/analytics).
* For the buyer's-eye view, see [Managing subscriptions](/buyers/managing-subscriptions) and [Refunds](/buyers/refunds).
* To embed subscriptions on your own site and handle webhooks, clone the [subscriptions example on GitHub](https://github.com/pocketsflow/subscriptions-example).