Skip to main content
Subscriptions handle anything you bill on a recurring cadence — monthly retainers, quarterly maintenance, annual SaaS plans, and usage-based services. They auto-generate invoices on schedule, prorate plan changes, retry failed payments per a configurable policy, and roll up into MRR/ARR reporting. The Subscriptions UI is at /dashboard/commerce/subscriptions/, with data in crm_subscriptions.

​
Subscription types

A fixed price billed on a fixed cadence. The simplest type — most retainers and SaaS plans.Example: “$3,000/month for SEO retainer.”

​
Setting up a subscription

1

Pick the client

Subscriptions tie to a CRM contact or company. The same client can have multiple active subscriptions (different services, different plans).
2

Pick the plan or product

From your Products catalog, pick the recurring product. For tiered plans, the plan-picker shows all is_plan: true products grouped together.
3

Set the start date

Today, a future date, or backdated. The first invoice generates on the start date (or on the next billing-cycle anchor — see proration below).
4

Set the billing frequency

Monthly, quarterly, semi-annual, or annual. Most retainers are monthly; SaaS-style plans are often monthly or annual with a discount for annual.
5

Set the billing anchor

The day of the month invoices generate. Day 1 is common; some businesses prefer the day-of-month matching the start date so each client has their own anchor.
6

Add line items

The base plan plus any add-ons. Each line item can have its own quantity and price overrides.
7

Activate

Confirm the configuration and click Activate. The subscription is now live; the first invoice generates on the next anchor.

​
Subscription statuses

  • active — Billing on schedule, no issues.
  • past_due — A generated invoice is unpaid past the dunning policy. The subscription stays active but the status flag warns you.
  • paused — Manually paused. No invoices generate until you resume.
  • canceled — Canceled by you or the client. No future invoices; keeps history for reporting.
  • trialing — In a free-trial period before the first paid invoice.

​
Plan changes

Three flavors of plan changes:
Move to a higher-priced plan effective immediately. The current cycle is prorated — client gets a credit for the unused portion of the old plan and is charged for the prorated remainder of the new plan. The next full cycle bills at the new plan price.
Default to “upgrade now, downgrade at renewal.” It matches most clients’ expectations — they want their upgrade right away and don’t want surprise charges from downgrading.

​
Pausing and canceling

  • Pause — Stops invoice generation but keeps the subscription record. Resume any time. Useful for seasonal clients or contractor breaks.
  • Cancel at end of cycle — Honors the current cycle (client got what they paid for) and stops at renewal. The default cancellation flow.
  • Cancel immediately — Stops billing on the spot. Optionally issues a prorated refund for the unused portion of the current cycle.
Canceled subscriptions retain their history for churn reporting and reactivation. To re-onboard a client, create a fresh subscription rather than reactivating the canceled one — the audit trail stays cleaner.

​
Failed payments and dunning

When an invoice generated by a subscription fails to charge, the dunning policy kicks in:
1

First retry (24 hours)

Automatic retry the next day, in case the failure was transient (insufficient funds that since cleared, etc.).
2

Second retry (3 days)

Another automatic retry, paired with an email to the client asking them to update their payment method.
3

Third retry (7 days)

Final automatic retry. Client gets a more urgent email.
4

Mark past_due

Subscription is flagged past_due. No more auto-retries. Your team is notified to follow up directly.
5

Cancel for non-payment

After a configurable grace period (default 14 days past_due), the subscription auto-cancels.
The retry intervals and grace period are configurable per account in Payment Settings.

​
Usage-based billing

For usage-priced subscriptions, record usage against the subscription throughout the cycle:
  • Manual — Enter usage in the subscription’s UI before the cycle closes.
  • API — POST /api/crm/subscriptions/:id/usage to record usage events from your application.
  • Imported — Periodic CSV upload for usage tracked elsewhere.
When the cycle’s invoice generates, recorded usage is summed and added as a separate line item. Past-cycle usage doesn’t carry forward — anything not billed in the cycle it occurred in is lost (so make sure your usage-recording cadence matches your cycle close).

​
MRR and ARR

Active subscriptions roll up into:
  • MRR (Monthly Recurring Revenue) — Sum of all monthly-equivalent subscription value.
    • A 99/monthsubcontributes99/month sub contributes 99.
    • A 999/yearsubcontributes999/year sub contributes 83.25 ($999 ÷ 12).
  • ARR (Annual Recurring Revenue) — MRR × 12.
  • New MRR — From new subscriptions this period.
  • Expansion MRR — From upgrades on existing subscriptions this period.
  • Churn MRR — From cancellations and downgrades this period.
  • Net MRR change — New + Expansion − Churn.
See Reports & Analytics for the full MRR/ARR dashboard.

​
API patterns

Common operations against /api/crm/subscriptions:
  • POST /api/crm/subscriptions — create a subscription
  • POST /api/crm/subscriptions/:id/activate — activate a draft
  • POST /api/crm/subscriptions/:id/pause — pause billing
  • POST /api/crm/subscriptions/:id/resume — resume from paused
  • POST /api/crm/subscriptions/:id/cancel — cancel (at end of cycle by default)
  • POST /api/crm/subscriptions/:id/change-plan — upgrade/downgrade
  • POST /api/crm/subscriptions/:id/usage — record usage event

​
Best practices

  • Standardize billing anchors. Either everyone bills on the 1st, or everyone bills on their start date. Mixing is operationally painful.
  • Use plans (is_plan: true) for tiers, not for one-off retainers. Plans imply self-serve change-ability; bespoke retainers usually don’t have that.
  • Don’t backdate subscriptions casually. Backdating generates immediate invoices for past cycles and confuses MRR reporting. If you need to backfill billing for completed work, send standalone invoices instead.
  • Match your usage-record cadence to your billing cycle. If you bill monthly but only sync usage quarterly, you’ll under-bill three months in a row.

​
Troubleshooting

Check the next-billing-date — it may not have arrived yet. Check the subscription’s activity log for any generation errors. Also verify the client’s payment method is on file (Stripe/Authorize.Net) and that the payment processor connection is healthy.
Proration math depends on the change type — upgrades prorate, downgrades-at-renewal don’t. Double-check which option you picked. The activity log shows the prorated amounts so you can verify the math.
Annual subscriptions divide by 12. Multi-month (quarterly) divides by 3. Trialing subs aren’t counted. If your MRR is missing recent expansion or showing churn that didn’t happen, check the subscription’s status — past_due and paused are still active for MRR purposes, while canceled isn’t.
Check the dunning policy in Payment Settings. Also check that your processor connection is authorized — Stripe OAuth tokens can expire, and a disconnected processor can’t retry.
Usage must be recorded before the cycle’s billing date. Late entries don’t backfill. If you need to charge for missed usage, add it as an ad-hoc line item on the next invoice with a clear description.

​
What’s next?

Set Up Recurring Subscriptions

Hands-on walkthrough of creating your first recurring sub.

Products Catalog

Build the recurring products subscriptions reference.

Reports & Analytics

MRR, ARR, and churn dashboards.

Payment Processing

Failed-payment policy and dunning configuration.