# Subscriptions

## **Overview**

The **Subscriptions** feature allows merchants to offer recurring billing for goods or services.\
With subscriptions, customers agree to be charged automatically at set intervals (e.g., weekly, monthly, annually) in exchange for ongoing access to merchant's product or service.

## **Use Cases**

Merchants offering recurring services such as SaaS platforms, memberships, subscription boxes, or digital content.

* **SaaS Platforms:** Monthly or annual software subscriptions.
* **Membership Services:** Gym memberships, online courses, clubs.
* **Subscription Boxes:** Recurring physical product delivery.
* **Digital Content Access:** Streaming services, e-book libraries.
* **Maintenance Plans:** Recurring service agreements.

## **Key Benefits**

* **Automated Billing:** Charges occur automatically at predefined intervals.
* **Customer Self-Service:** Customers can manage their subscriptions, payment methods, and billing details via the dedicated Subscriber Portal.
* **Flexible Management:** Merchants can view, update, or cancel subscriptions directly via API or CRM.
* **Reduced Churn:**&#x20;
* **Reusable Payment Methods:** Secure storage of customer cards for future billing.
* **Configure Retry Rules:** Automated retries for failed payments help retain customers. \
  Merchant can set retries (e.g., 4 retries every 7 days) to reduce churn from failed payments.
* **Use Upcoming Renewal Emails:** Remind customers 7 days before renewal to reduce disputes.
* **Monitor Past-Due Subscriptions:** Act quickly to recover failed payments.

## **How it Works**

### Subscription Lifecycle

1. **Creation**
   * Customer selects a subscription plan on merchant's website.
   * Provides payment details and authorizes recurring charges.
   * The first payment is processed; subscription becomes _Active_.
2. **Renewals**
   * At each billing cycle, the system automatically generates an invoice and attempts payment.
   * On successful payment, the subscription remains _Active._
   * Receipt is sent to customer's email.
3. **Failed Payments**
   * If payment fails, the subscription moves to _Past-Due_ status.
   * The system retries payment according to pre-determined retry schedule.
   * If retries fail, the subscription may be marked _Unpaid_ or _Cancelled_ depending on the settings.
4. **Cancellation**
   * A subscription can be cancelled by the merchant, the customer (via dedicated Subscriber Portal), or automatically after failed payments if configured.
   * No further billing occurs.
5. **Completion**
   * Subscriptions with a set end date automatically move to _Completed_ status at the end of the term.

#### Subscription Status Overview

| Status                 | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| **Incomplete**         | Initial payment pending or failed.                           |
| **Incomplete-Expired** | Subscription never activated within allowed time (24 hours). |
| **Active**             | Payment successful; subscription running.                    |
| **Past-Due**           | Renewal payment failed; retry attempts in progress.          |
| **Unpaid**             | All retries failed; invoice uncollectible.                   |
| **Cancelled**          | Ended by customer, merchant, or system rules.                |
| **Completed**          | Ended as scheduled; no more billing.                         |

#### Invoice Status Overview

| Status            | Description                                                                                                                                                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Open**          | Invoice created and awaiting payment. For subscriptions, invoices are automatically finalized at the start of the billing cycle. If automatic payment fails or no payment method is available, the invoice remains open. |
| **Paid**          | Payment succeeded; invoice closed. Subscription continues normally.                                                                                                                                                      |
| **Uncollectible** | All payment retries failed; dunning process ended. Invoice is marked as uncollectible. Subscription transitions to _Unpaid_.                                                                                             |
| **Void**          | Invoice was canceled (voided) (e.g., if the subscription was canceled before the billing period began).                                                                                                                  |

#### Flow Diagram

{% @mermaid/diagram content="sequenceDiagram
    
    participant Customer
    participant Merchant Website
    participant Payment Gateway
    participant Subscription System
    participant Email Service

    Customer->>Merchant Website: Select subscription plan
    Merchant Website->>Customer: Request payment details
    Customer->>Merchant Website: Provide payment details and authorize recurring charges
    Merchant Website->>Payment Gateway: Process first payment
    Payment Gateway-->>Merchant Website: Payment success
    Merchant Website->>Subscription System: Activate subscription
    Subscription System->>Customer: Subscription Active confirmation
    Subscription System->>Email Service: Send receipt email
    Email Service-->>Customer: Receipt email

    loop Each billing cycle
        Subscription System->>Subscription System: Generate invoice
        Subscription System->>Payment Gateway: Attempt payment
        alt Payment success
            Payment Gateway-->>Subscription System: Payment success
            Subscription System->>Email Service: Send receipt email
            Email Service-->>Customer: Receipt email
        else Payment failure
            Payment Gateway-->>Subscription System: Payment failed
            Subscription System->>Subscription System: Mark as Past-Due
            Subscription System->>Payment Gateway: Retry payment (per schedule)
            alt Retry success
                Payment Gateway-->>Subscription System: Payment success
                Subscription System->>Email Service: Send receipt email
                Email Service-->>Customer: Receipt email
            else Retry failure
                Payment Gateway-->>Subscription System: Payment failed
                Subscription System->>Subscription System: Mark as Unpaid or Cancelled
            end
        end
    end

    alt Cancellation
        Customer->>Subscription System: Cancel via portal
        Subscription System->>Subscription System: Stop further billing
    else Merchant cancellation
        Merchant Website->>Subscription System: Cancel subscription
        Subscription System->>Subscription System: Stop further billing
    else Auto-cancel after failed payments
        Subscription System->>Subscription System: Cancel subscription
    end

    alt Completion at end date
        Subscription System->>Subscription System: Mark as Completed
    end

" fullWidth="true" %}

## Customer Email  Notifications



**1. Default Email Events**

* **When a subscription is started**\
  – Email will be triggered as soon as a new subscription starts.
* **When a subscription is finished**\
  – Email will be triggered when a subscription's end date is reached.

**2. Customizable Email Events**

* **Upcoming Renewals**\
  – Email will be sent **7 days before renewal** if the billing period is longer than 7 days.
* **Expiring Cards**\
  – Email will be sent **1 month before the card expiration date**.\
  – If a new card is added within the expiration month, the email will be sent within **24 hours**.
* **Failed Card Payment Updates**\
  – Email will be sent **every time a payment attempt fails**, including retries.
* **When an Invoice is Paid**\
  – Email with Receipt will be sent as soon as an invoice is successfully paid.

## FAQ

<details>

<summary>❓Can customers change their payment method?</summary>

Yes. Customers can update payment details via the Subscriber Portal.

</details>

<details>

<summary>❓What happens if a payment fails?</summary>

The system retries payment per predefined retry settings.\
If unsuccessful, the subscription moves to **Unpaid** or **Canceled** depending on the configuration.

</details>

<details>

<summary>❓Can I set different billing intervals?</summary>

Yes. Subscriptions can be billed **daily**, **weekly**, **monthly**, or **annually**, with customizable interval counts.

</details>

<details>

<summary>❓Can I cancel a subscription immediately?</summary>

Yes. You can cancel via **CRM** or **API**, and customers can cancel from the **Subscriber Portal**.

</details>

<details>

<summary>❓What payment processors are supported?</summary>

Any PSP configured in your account that supports:

* Merchant-Initiated Transactions (MIT)
* Zero-Amount Authorization
* Gateway-Side Tokenization

</details>

