Introduce Pausing Subscriptions

Problem Statement

Pelcro currently lacks a native “pause subscription” capability, forcing subscribers to cancel when they want a temporary break. This creates unnecessary churn, disrupts subscription lifecycle continuity, and negatively impacts retention metrics.

Clients need a flexible, controlled way to allow subscribers to temporarily stop billing and access without terminating their subscription. Additionally, the absence of structured pause rules (e.g., duration limits, frequency caps) prevents consistent business logic across clients.

User Story

As a subscriber,
I want to pause my subscription for up to 90 days once per year,
So that I can temporarily stop billing and access without canceling my subscription, while retaining the ability to resume at any time.

As an admin,
I want the ability to override pause/resume states,
So that I can assist users and resolve edge cases or support issues.

Proposed Solution

Introduce a Pause Subscription feature with controlled rules:

• Subscribers can pause their subscription once per calendar year

• Maximum pause duration: 90 days

• Billing is fully stopped during the pause

• Subscription automatically resumes at the end of the selected period

• Users can resume early at any time

• During pause, user access downgrades to free-tier entitlements

• Admins can override pause/resume states

This feature must follow Pelcro’s API-first architecture, with full support across UI, API, SDK, and webhook layers.

Scope & Components Affected

UI (React Elements)

• Add “Pause Subscription” option in account settings

• Duration selector (up to 90 days)

• Display:

  • Pause status

  • Remaining pause time

  • Resume button (early resume)

• Messaging for:

  • “Once per year” restriction

  • Access downgrade during pause

API (Laravel Backend)

• New endpoints:

  • POST /subscriptions/{id}/pause

  • POST /subscriptions/{id}/resume

• Extend subscription resource:

  • pause_start_at

  • pause_end_at

  • pause_used_this_year (boolean or counter)

• Logic for:

  • Enforcing one pause per year

  • Validating max 90-day duration

  • Blocking billing during pause

  • Automatic resume job (cron/queue)

SDK (JS-SDK)

• Methods:

  • pauseSubscription(subscriptionId, duration)

  • resumeSubscription(subscriptionId)

• Expose pause metadata in subscription object

Admin / Dashboard

• Admin controls to:

  • Force pause

  • Force resume

  • Override annual limit (if needed)

• Visibility into pause history

Webhooks / Integrations

• Events:

  • subscription.paused

  • subscription.resumed

• Include metadata:

  • Pause duration

  • Resume trigger (auto vs manual vs admin)

Key Functional Requirements

• Users can pause:

  • Only once per year

  • For a maximum of 90 days

• Billing:

  • Fully stopped during pause

  • Resumes normally after pause

• Access:

  • Downgraded to free account level

• Resume:

  • Manual (anytime)

  • Automatic (end of pause period)

• Applies to:

  • Monthly subscriptions

  • Annual subscriptions

  • Bundles / all subscription types

• Admin override:

  • Required for support and edge cases

Impact & Business Context

• Client Impact: High — enables modern retention strategy used by leading subscription platforms

• Revenue Impact:

  • Short-term: deferred revenue

  • Long-term: reduced churn, improved LTV

• User Experience: Significantly improved flexibility and control

• Operational Impact: Requires support tooling (admin overrides)

• Adoption: Likely high across all Pelcro clients

Risks & Considerations

• Billing Complexity:

  • Handling mid-cycle pauses (especially annual plans)

• Entitlement Sync:

  • Ensuring real-time downgrade to free tier

• Abuse Prevention:

  • Annual limit enforcement critical

• Analytics Impact:

  • Need clear distinction between paused vs churned users