Client Subscriptions

Client subscriptions are recurring billing arrangements between your workspace and a contact or company. When you set up a subscription, concorbit automatically generates invoices on billing dates, tracks the subscription lifecycle, and optionally integrates with Stripe for automatic payment collection.

Client subscriptions are distinct from your workspace's own concorbit platform subscription. Client subscriptions are the recurring billing you set up for your customers.

Two separate records: client_subscription and billing_subscription

The model is intentionally split:

• client_subscription is the commercial record. It captures who the customer is, what they bought, how much per unit, the interval, the trial, and the lifecycle (active, trialing, paused, cancelled). No Stripe identifiers live here.

• billing_subscription is the money-movement record. It carries the Stripe Connect account id, the customer id, the mandate, the payment method, retry state, and a frozen snapshot of the collection policy resolved at creation time.

A client subscription with a recurring card collection mode gets paired with a billing subscription on first renewal. Renewals read the billing subscription's frozen snapshot, never live product or company defaults, so a later change to a default cannot silently re-route or re-price an active agreement.

Recurring card agreements are off-session PaymentIntents, not Stripe Subscriptions

A key architectural decision: concorbit does not use Stripe-native Subscriptions for recurring card agreements. Instead, RecurringBillingAgreementService::renew runs invoice-driven, off-session PaymentIntent charges on the connected account, mirroring how AutopayService works.

The reasons:

• concorbit's invoice is the customer-facing artefact, not Stripe's.

• Dunning, retry budgets, the £0 paid lifecycle, and tax handling all stay in concorbit's lifecycle.

• The same code path serves recurring agreements and one-off-card autopay, so there is one charging code path, not two.

Per renewal, the service idempotency-keys the PaymentIntent, asserts the agreement is chargeable (ownership match, no open dispute, collection mode is a card mode), and records the settlement via PaymentLedgerService. The frozen policy snapshot is the agreement's source of truth.

Dunning is per-invoice, not per-subscription

When an autopay attempt fails, concorbit retries on a fixed schedule of 1, 3, 7 days after the first failure. The retry budget lives on the invoice (invoices.dunning_attempts), not the subscription. That means:

• Each invoice has its own independent retry schedule.

• A cancelled subscription's last invoice still retries until its budget is exhausted (or the cancellation explicitly stops it).

• An expired or paused subscription does not freeze other invoices' retries.

Once the schedule is exhausted, the invoice is left unpaid for manual follow-up. See Autopay for the eligibility rules and the dispute freeze that override the retry schedule.

Subscription Lifecycle

Every subscription has a status:

Billable Statuses

Only subscriptions in Active or Trialing status are considered billable. Auto-invoicing only runs for subscriptions in these statuses.

Creating a Subscription

1. Navigate to Subscriptions in the sidebar.

2. Click New Subscription.

3. Fill in the subscription details:

   • Contact: Select the contact being billed (from CRM).

   • Company: Optionally link the subscription to a company.

   • Product: Select a product from your catalogue. The product's price and billing interval are used as defaults.

   • Price: The per-unit price for this subscription (copied from the product, but can be overridden). Stored in minor currency units.

   • Quantity: Number of units (e.g. 5 users, 10 devices).

   • Billing interval: Monthly, Quarterly, or Annual.

   • Currency: Defaults to the product's or workspace's currency.

   • Trial days: Optional trial period before first billing (inherited from product, can be overridden).

4. Click Create.

What Happens at Creation

• The subscription is created with a status of Active (or Trialing if trial days are set).

• The current billing period is established (start date, end date, next billing date).

• If a trial is configured, the trial_ends_at date is set and the first invoice is deferred until after the trial.

Subscription Intervals

The billing interval determines how often auto-invoicing generates a new invoice for the subscription.

Auto-Invoicing

When a subscription's next billing date arrives, concorbit automatically:

1. Creates a new invoice with line items based on the subscription's product, price, and quantity.

2. Links the invoice to the subscription for traceability.

3. Sends the invoice to the contact.

4. Advances the subscription's billing period to the next cycle.

Auto-invoicing runs once a day via the scheduled run-subscription-billing command, which emits charges (emit-subscription-charges) then collects invoices (collect-subscription-invoices) in one sequential pass. Subscriptions are only invoiced when their next_billing_at date has passed and their status is Active or Trialing.

Monthly Recurring Revenue (MRR)

concorbit calculates the monthly-equivalent value of each subscription for MRR reporting:

The Subscription Stats dashboard widget aggregates MRR across all active subscriptions.

Editing a Subscription

You can edit the following fields on an active or trialing subscription:

• Price: Change the per-unit price.

• Quantity: Change the number of units.

• Billing interval: Change how often the subscription is billed.

To edit:

1. Navigate to Subscriptions.

2. Click on the subscription.

3. Click Edit.

4. Make your changes.

5. Click Save.

Price and quantity changes take effect on the next billing cycle. The current period is not affected.

Pausing a Subscription

To temporarily suspend billing:

1. Open the subscription.

2. Click Pause.

3. The subscription status changes to Paused.

4. The pause date and time are recorded.

While paused:

• No invoices are generated.

• The billing period clock stops.

• The subscription can be resumed at any time.

Setting a Resume Date

When pausing, you can optionally set a future resume date. When the resume date arrives, the subscription automatically resumes.

Resuming a Subscription

To restart a paused subscription:

1. Open the paused subscription.

2. Click Resume.

3. The subscription status changes to Active.

4. The billing period is recalculated from the resume date.

Cancelling a Subscription

To permanently end a subscription:

1. Open the subscription.

2. Click Cancel.

3. Optionally provide a cancellation reason and feedback (these are encrypted at rest for privacy).

4. The subscription status changes to Cancelled.

5. The cancellation date is recorded.

Cancelled subscriptions cannot be resumed. If the contact wants to restart service, create a new subscription.

What Happens After Cancellation

• No further invoices are generated.

• Existing unpaid invoices remain outstanding and should be followed up.

• The subscription record is retained for historical reporting and MRR analysis.

Payment Failures and Dunning

When a Stripe autopay attempt fails:

1. The payment failure is recorded on the subscription.

2. The payment_failures counter increments.

3. The last_failure_at timestamp is updated.

If payment failures accumulate, the subscription may transition to Past due status. Past-due subscriptions continue to exist but need manual attention, either the payment method should be updated, or the subscription should be cancelled.

Prorated Billing

When you change the price or quantity of an active subscription mid-cycle, the change takes effect on the next billing date. concorbit does not automatically generate a prorated invoice for the remainder of the current period. If prorated billing is needed, create a manual invoice for the difference.

For Stripe-managed subscriptions, Stripe's built-in proration logic handles mid-cycle changes automatically.

Stripe Integration for Recurring Payments

When your workspace has Stripe Connect configured and a contact has a stored payment method with autopay enabled:

1. The subscription's auto-generated invoice is created.

2. concorbit initiates a Stripe charge against the contact's default payment method.

3. If the charge succeeds, the invoice is automatically marked as paid.

4. If the charge fails, the invoice remains unpaid and the payment failure is recorded on the subscription.

See Payments & Stripe for details on setting up Stripe, managing payment methods, and configuring autopay.

Autopay Configuration

Autopay must be enabled at the contact level, not the subscription level. When a contact has autopay enabled and a default payment method on file:

• All subscriptions for that contact will attempt automatic payment when invoices are generated.

• The contact can manage their payment methods and autopay preference through the client portal.

Viewing Subscription History

Each subscription shows:

• The linked invoices (all invoices generated by this subscription).

• The current billing period (start and end dates).

• The next billing date.

• Payment failure history.

• Cancellation details (if cancelled).

Subscription Scopes and Filtering

On the Subscriptions page, you can filter by:

• Status: Active, Trialing, Paused, Past due, Cancelled, Expired.

• Contact: View subscriptions for a specific contact.

• Company: View subscriptions for a specific company.

On the canvas, the Subscription List panel filters by contact or company when one is selected.

Canvas Panels

The Billing module provides these subscription-related canvas panels:

• Subscription List: Shows subscriptions with status badges. Filters by contact/company in context.

• Subscription Stats: Active count, MRR, and churn metrics.

• Subscription Detail: Single subscription view with inline editing (price, quantity, interval) and workflow buttons (pause, resume, cancel).

Best Practices

• Use products for consistency: Always link subscriptions to products from your catalogue. This ensures consistent pricing and makes reporting easier.

• Set trial periods on products: Configure trial days on the product rather than overriding per subscription. This ensures a consistent trial policy.

• Monitor past-due subscriptions: Check the Subscription Stats widget regularly. Past-due subscriptions indicate payment problems that need attention.

• Use autopay: Encourage contacts to set up autopay to reduce payment delays and manual follow-up.

• Document cancellation reasons: When cancelling, always record the reason. This data helps you understand churn patterns.

• Review MRR trends: Track your MRR over time using the Subscription Stats widget. Growing MRR is a key health metric for recurring-revenue businesses.