> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Recurring billing for retainers, SaaS-style plans, and usage-based services with proration, plan changes, and MRR roll-up

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

<Tabs>
  <Tab title="Flat recurring">
    A fixed price billed on a fixed cadence. The simplest type — most retainers and SaaS plans.

    Example: "\$3,000/month for SEO retainer."
  </Tab>

  <Tab title="Tiered plans">
    A subscription tied to a `is_plan: true` product. Plans are easy to upgrade/downgrade between, and they roll up into MRR by tier.

    Example: "Starter ($99/mo), Pro ($299/mo), Enterprise (\$999/mo)."
  </Tab>

  <Tab title="Usage-based">
    Price scales with consumption. Configure a unit (per seat, per call, per GB), unit price, and any included quantity. Usage is recorded against the subscription and billed on the next cycle.

    Example: "\$0.001 per API request, first 10,000 included."
  </Tab>

  <Tab title="Hybrid (base + usage)">
    A flat base plan plus usage-based add-ons. Most common for SaaS where the base plan covers core features and usage drives overage charges.

    Example: "$499/month base + $0.10 per extra seat over 25."
  </Tab>
</Tabs>

## Setting up a subscription

<Steps>
  <Step title="Pick the client">
    Subscriptions tie to a CRM contact or company. The same client can have multiple active subscriptions (different services, different plans).
  </Step>

  <Step title="Pick the plan or product">
    From your [Products catalog](/commerce/products), pick the recurring product. For tiered plans, the plan-picker shows all `is_plan: true` products grouped together.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Add line items">
    The base plan plus any add-ons. Each line item can have its own quantity and price overrides.
  </Step>

  <Step title="Activate">
    Confirm the configuration and click **Activate**. The subscription is now live; the first invoice generates on the next anchor.
  </Step>
</Steps>

## 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:

<Tabs>
  <Tab title="Upgrade (immediate)">
    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.
  </Tab>

  <Tab title="Downgrade (at next renewal)">
    Move to a lower-priced plan effective at the next billing cycle. No proration; client finishes the current cycle at the old price, then renews at the new price.
  </Tab>

  <Tab title="Same-day swap (no proration)">
    For changes that shouldn't generate a credit/charge (e.g., a billing-only rename), swap the plan with proration disabled. The current cycle finishes at the old price; next cycle uses the new plan.
  </Tab>
</Tabs>

<Tip>
  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.
</Tip>

## 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:

<Steps>
  <Step title="First retry (24 hours)">
    Automatic retry the next day, in case the failure was transient (insufficient funds that since cleared, etc.).
  </Step>

  <Step title="Second retry (3 days)">
    Another automatic retry, paired with an email to the client asking them to update their payment method.
  </Step>

  <Step title="Third retry (7 days)">
    Final automatic retry. Client gets a more urgent email.
  </Step>

  <Step title="Mark past_due">
    Subscription is flagged `past_due`. No more auto-retries. Your team is notified to follow up directly.
  </Step>

  <Step title="Cancel for non-payment">
    After a configurable grace period (default 14 days past\_due), the subscription auto-cancels.
  </Step>
</Steps>

The retry intervals and grace period are configurable per account in [Payment Settings](/commerce/payments).

## 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/month sub contributes $99.
  * A $999/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](/commerce/reports) 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

<AccordionGroup>
  <Accordion title="Subscription is active but no invoice generated">
    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](/commerce/payments) is healthy.
  </Accordion>

  <Accordion title="Plan change didn't prorate the way I expected">
    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.
  </Accordion>

  <Accordion title="MRR number looks wrong">
    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.
  </Accordion>

  <Accordion title="Failed payment retries aren't running">
    Check the dunning policy in [Payment Settings](/commerce/payments). Also check that your processor connection is authorized — Stripe OAuth tokens can expire, and a disconnected processor can't retry.
  </Accordion>

  <Accordion title="Usage line item didn't appear on the invoice">
    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.
  </Accordion>
</AccordionGroup>

## What's next?

<CardGroup cols={2}>
  <Card title="Set Up Recurring Subscriptions" icon="rocket" href="/how-tos/setup-recurring-subscription">
    Hands-on walkthrough of creating your first recurring sub.
  </Card>

  <Card title="Products Catalog" icon="box" href="/commerce/products">
    Build the recurring products subscriptions reference.
  </Card>

  <Card title="Reports & Analytics" icon="chart-line" href="/commerce/reports">
    MRR, ARR, and churn dashboards.
  </Card>

  <Card title="Payment Processing" icon="credit-card" href="/commerce/payments">
    Failed-payment policy and dunning configuration.
  </Card>
</CardGroup>