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

# Subscriptions

## Overview

The Subscriptions module powers recurring billing in Ecrypt. Use it to charge customers automatically on a defined cadence — daily, weekly, monthly, quarterly, annually, and more — using either their saved credit card or ACH account. Subscriptions support optional installment plans, automated email receipts, "skip first payment" trials, and full lifecycle management including pause, cancel, edit, and early payment.

Key capabilities:

* 11 built-in billing cycles ranging from Daily to Annually, including semi-monthly variants
* Use an existing Customer Vault record or create a new customer inline
* Credit card or ACH as the recurring payment method
* Installment billing with a configurable number of payments
* Pause, cancel, edit, or charge a subscription early at any time
* Real-time KPIs (Successful Payments, New Subscriptions, Declined Payments) with period-over-period change
* Full payment history per subscription and aggregated across all subscriptions

***

## Navigation

Subscriptions lives in the left sidebar under **APPS → Subscriptions**, which expands to three sub-sections:

| Sub-section           | Path                               | Purpose                                               |
| --------------------- | ---------------------------------- | ----------------------------------------------------- |
| **Dashboard**         | `/subscriptions/dashboard`         | KPIs + upcoming payments in a chosen date range       |
| **Payments**          | `/subscriptions/payments`          | Every recurring charge attempt, success or failure    |
| **All Subscriptions** | `/subscriptions/all-subscriptions` | The complete list of subscriptions filtered by status |

Subscriptions can also be created from the sidebar's **ACTIONS → Add Subscriptions** quick action.

***

## Subscriptions → Dashboard

The Dashboard opens with three KPI cards and a date-filtered table of upcoming subscription payments.

### KPI Cards

Each card shows a count plus an arrow indicator and percentage compared to the previous 7-day period.

| Card                    | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| **SUCCESSFUL PAYMENTS** | Number of recurring charges that succeeded in the period |
| **NEW SUBSCRIPTIONS**   | Count of subscriptions created in the period             |
| **DECLINED PAYMENTS**   | Number of failed recurring charges in the period         |

The colored percentage indicates change versus PREV. 7 DAYS — green up-arrow for increase, red down-arrow for decrease.

### Date Range Selector

| Control                          | Description                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Next Payment Date Range** chip | Defaults to the current rolling 7-day window (e.g., 05-21-26 — 05-27-26). Click to open a date range picker. |
| **PAYMENTS** button              | Top-right blue button — jumps to the Subscriptions → Payments page                                           |

### Filter Panel

Click **FILTERS** to expand the filter bar; **CLEAR FILTERS** resets it. An active filter chip appears next to **Filter By:** (e.g., "Next Payment Date range : 05/21/2026 - 05/27/2026").

### Upcoming Payments Table

| Column              | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| **Next Payment**    | Date the next recurring charge will run                       |
| **Billing Cycle**   | Cadence (Daily, Weekly, Monthly, etc.)                        |
| **Last Payment**    | Date the most recent charge was attempted                     |
| **Status**          | Subscription status (Active, Cancelled, Suspended, Completed) |
| **Account Data**    | Masked card or ACH account (with brand logo)                  |
| **Customer**        | Customer name from the vault                                  |
| **Created Date**    | When the subscription was set up                              |
| **Subscription ID** | Unique subscription UUID                                      |

Clicking any row opens the **Subscription Detail panel** (see below).

***

## Subscription Detail Panel

Clicking a subscription row anywhere in the Subscriptions module opens a comprehensive detail panel.

### Header

| Element                | Description                                         |
| ---------------------- | --------------------------------------------------- |
| **Status badge**       | SETTLED, PENDING, DECLINED, etc. (color-coded)      |
| **Timestamp**          | Date and time of the most recent payment            |
| **Merchant**           | Merchant account (e.g., MIAMI)                      |
| **Initiated By**       | User or API key that created the subscription       |
| **Transaction #**      | Latest transaction ID                               |
| **Billing badge**      | Blue chip: "BILLED DAILY" / "BILLED MONTHLY" / etc. |
| **Next Payment badge** | Blue chip: "NEXT PAYMENT DATE: \[DATE]"             |
| **Subscription ID**    | Full UUID (gold/highlighted)                        |

### Info Row Chips

| Chip              | Example  |
| ----------------- | -------- |
| **RESPONSE**      | APPROVED |
| **APPROVAL CODE** | 123456   |
| **CURRENCY**      | USD      |
| **ENTRY MODE**    | KEYED    |

### Card Visual

A large card-shaped panel shows:

* Customer name (e.g., JJ TEST)
* Payment Amount (large dollar amount)
* Card Number (masked, e.g., 543111\*\*\*\*\*\*1111)
* Date (expiration MM/YY)
* Card brand logo (MasterCard, Visa, etc.)

### Body Sections

| Section               | Fields                                                                                 |
| --------------------- | -------------------------------------------------------------------------------------- |
| **Billing Address**   | Address text                                                                           |
| **Shipping Address**  | Address text (or N/A)                                                                  |
| **More Info**         | Subtotal, Tax, Surcharge, AVS Status, CVV Status                                       |
| **Subscription Info** | Billing Cycle, Installments (with tooltip showing total count), Send Receipts (Yes/No) |
| **Order Information** | Optional order metadata or N/A                                                         |

### Left Panel — MENU & ACTIONS

The left sidebar of the detail panel groups actions into three buckets:

**MENU**

| Item                    | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| **Payment Information** | The main detail view (default)                                |
| **Transaction History** | Jumps to Subscriptions Payments filtered to this subscription |

**ACTIONS** (general transaction actions)

| Action                 | Description                              |
| ---------------------- | ---------------------------------------- |
| **Refund Transaction** | Refund the most recent charge            |
| **View Receipt**       | Open the printable/emailable receipt     |
| **Charge Again**       | Run a one-off charge using the same card |
| **View Customer**      | Jump to the customer's vault profile     |

**ACTIONS FOR SUBSCRIPTIONS** (subscription lifecycle)

| Action                   | Description                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **Subscription History** | Opens the list of all charges run on this subscription (Payment Date, Account Data, Customer, Amount, Status, Subscription ID) |
| **Pay Early**            | Triggers the next scheduled charge immediately                                                                                 |
| **Cancel Subscription**  | Permanently cancels (sets status to Cancelled)                                                                                 |
| **Pause Subscription**   | Temporarily suspends recurring charges                                                                                         |
| **Edit Subscription**    | Opens the edit form (amount, tax, payment method)                                                                              |

### Edit Subscription Form

Opened from the **Edit Subscription** action. The right side shows a live **Pricing Summary** (Amount, Estimated tax, Surcharge, Total).

| Field                        | Required | Notes                                           |
| ---------------------------- | -------- | ----------------------------------------------- |
| **Amount**                   | Yes      | Recurring charge amount in USD                  |
| **Tax (Exclusive)**          | No       | Percentage applied on top of the amount         |
| **+ ADD NEW PAYMENT METHOD** | —        | Adds a new card or ACH to the customer's wallet |
| **Current Card tile**        | —        | Shows existing card; click **UPDATE** to edit   |
| **Billing Address**          | —        | Shown with **UPDATE** link                      |

> **Note:** A warning banner appears for debit cards: "Surcharge removed. Debit cards are not eligible for surcharge fees."

Click **EDIT SUBSCRIPTION** to save changes.

### Pause / Cancel / Pay Early Confirmation Panels

These three actions each open a confirmation panel showing the subscription summary (status badge, billing badge, next payment date, subscription ID, info row chips, subscription amount, card details, subscription info) plus a single primary button:

| Action              | Confirmation Button        |
| ------------------- | -------------------------- |
| Pause Subscription  | **PAUSE SUBSCRIPTION**     |
| Cancel Subscription | **CANCEL SUBSCRIPTION**    |
| Pay Early           | **PAY SUBSCRIPTION EARLY** |

***

## Subscriptions → Payments

A table of every recurring charge attempt — both successes and declines — across all subscriptions.

### Columns

| Column                   | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| **Next Payment**         | Next scheduled charge date (N/A if completed/cancelled) |
| **Billing Cycle**        | Cadence at time of charge                               |
| **Payment Date**         | When this charge was attempted                          |
| **Status**               | Success (green) or Declined (red)                       |
| **Account Data**         | Masked card/ACH with brand logo                         |
| **Customer**             | Customer name                                           |
| **Amount**               | Charge amount in USD                                    |
| **Subscription Created** | Original subscription creation date                     |
| **Subscription ID**      | Unique subscription identifier                          |

### Filter Panel

The **Filter By** dropdown supports filtering on any column:

| Filter Field         |
| -------------------- |
| Next Payment         |
| Billing Cycle        |
| Payment Date         |
| Status               |
| Account Data         |
| Customer             |
| Amount               |
| Subscription Created |
| Subscription ID      |

Workflow: select **Filter By** → choose **Filter Type** (equals, greater than, contains, etc.) → enter **Value** → **+ ADD FILTER** (to stack) → **APPLY FILTERS**.

Clicking any row opens the same Subscription Detail panel described above.

***

## Subscriptions → All Subscriptions

The master list of every subscription, scoped by status.

### Status Filter Tabs (top right)

| Tab           | Description                             |
| ------------- | --------------------------------------- |
| **Active**    | Currently recurring (default)           |
| **Cancelled** | Permanently ended                       |
| **Suspended** | Paused — no charges running             |
| **Completed** | Installment plans that have finished    |
| **All**       | Every subscription regardless of status |

A **PAYMENTS** button (top right, blue) jumps to the Subscriptions → Payments view.

### Columns

| Column              | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Next Payment**    | Next scheduled charge date                              |
| **Billing Cycle**   | Cadence                                                 |
| **Last Payment**    | Most recent charge date                                 |
| **Status**          | Active / Cancelled / Suspended / Completed              |
| **Account Data**    | Masked payment method                                   |
| **Customer**        | Customer name                                           |
| **Created Date**    | Subscription start (sortable — click the column header) |
| **Subscription ID** | Unique UUID                                             |

The **Filter By:** chip shows the active status filter (e.g., "Status equals : Active") and can be cleared via the red X.

***

## Creating a Subscription — Add Subscriptions Action

Available in the sidebar under **ACTIONS → Add Subscriptions** (or by URL `?actions=add-subscriptions`).

### Step 1 — Choose Customer

The modal opens with the question "Is this a new or existing customer?"

| Option                  | Action                                                               |
| ----------------------- | -------------------------------------------------------------------- |
| **NEW CUSTOMER** button | Creates a new customer inline (opens the standard Add Customer form) |
| Search box (below "OR") | Type to find an existing vault customer; click a result to select    |

### Step 2 — Build the Subscription

After selecting a customer, the full subscription form appears.

#### Billing Cycle (required)

Dropdown with 11 options:

| Value                      |
| -------------------------- |
| Daily                      |
| Weekly                     |
| Bi-Weekly                  |
| Semi-Monthly (1st & 15th)  |
| Semi-Monthly (15th & Last) |
| Monthly                    |
| Monthly (1st)              |
| Monthly (Last)             |
| Quarterly                  |
| Semi-Annually              |
| Annually                   |

#### Core Fields

| Field                 | Required | Notes                                           |
| --------------------- | -------- | ----------------------------------------------- |
| **Amount**            | Yes      | Recurring charge amount in USD (default \$0.00) |
| **Tax (Exclusive)**   | No       | Percentage applied on top of the amount         |
| **Next Payment Date** | Yes      | Date picker; defaults to today                  |

#### Payment Method

The customer's existing wallet cards are shown as a tile with an **UPDATE** badge. The **Billing Address** below shows with an **UPDATE** link.

To add a new card or ACH account, click **+ ADD NEW PAYMENT METHOD** to expand:

| Field                  | Required | Notes                    |
| ---------------------- | -------- | ------------------------ |
| **Customer Wallet**    | Yes      | Radio: Credit Card / ACH |
| **Name On Card**       | Yes      | Cardholder full name     |
| **Credit Card Number** | Yes      | 15–16 digit card number  |
| **Expiration Date**    | Yes      | MM/YY format             |
| **Street Address**     | Yes      | Billing street           |
| **City**               | Yes      | Billing city             |
| **State**              | Yes      | Billing state            |
| **Zip code**           | Yes      | Billing ZIP              |

(Switching to **ACH** replaces card fields with Name On Account, Account Number, Routing Number.) Click **CANCEL ADDING NEW PAYMENT METHOD** to collapse the form.

#### Subscription Options

| Option                   | Default | Notes                                                                                                                                                        |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **☐ Installments**       | Off     | *"Enables installment billing, charging the subscription amount across a set number of payments."* When checked, a **Number of Installments** field appears. |
| **☑ Send Receipts**      | On      | *"Enables email receipts for all recurring subscription payments."* When checked, an **Email** field is shown and pre-filled from the customer profile.      |
| **☐ Skip First Payment** | Off     | *"When enabled, the first subscription payment is skipped and billing begins with the next scheduled cycle."* Useful for free-trial scenarios.               |

### Pricing Summary (right panel)

Updates in real time as you change Amount and Tax:

* Amount
* Estimated tax
* Surcharge
* **Total** (large, highlighted)

### Submit

Click **ADD SUBSCRIPTION** (large blue button) to create the subscription. The new record appears immediately in All Subscriptions and is included in the next Dashboard refresh.

***

## Tips & Best Practices

**Choosing the Right Billing Cycle.** Use Semi-Monthly variants (1st & 15th or 15th & Last) for payroll-aligned subscriptions. Use Monthly (1st) or Monthly (Last) when you need charges to land predictably on the same day each month rather than 30 days from the start date. For consumer subscriptions, Monthly or Annually is the most common.

**Installments vs. Open-Ended.** Leave Installments unchecked for ongoing subscriptions (gym memberships, SaaS). Check Installments and set Number of Installments to convert a large one-time charge into a fixed payment plan (e.g., $1,200 over 12 monthly installments of $100).

**Skip First Payment for Trials.** Combine Skip First Payment with a future Next Payment Date to implement a free trial. Billing begins on the next scheduled cycle date.

**Pause vs. Cancel.** Pausing keeps the subscription record and payment method intact so you can resume later. Cancel is permanent — if the customer returns, you'll need to create a new subscription.

**Pay Early for Catch-Up.** Use Pay Early when a customer wants to settle their next installment ahead of schedule, or when you need to recover a previously declined charge without waiting for the next cycle.

**Watching Declined Payments.** The Declined Payments KPI on the Dashboard is your early warning for failing recurring charges (expired cards, insufficient funds, fraud blocks). Drill into Subscriptions → Payments and filter Status = Declined to triage.

**Date Range for the Dashboard.** The default 7-day window is great for daily ops. Widen the range to 30 or 90 days during monthly retention reviews or churn analysis.

**Editing the Card Without Recreating the Subscription.** Use Edit Subscription → Update on the card tile (or + Add New Payment Method) when a customer's card is replaced or expired. The subscription continues uninterrupted.

**Sortable Created Date.** In All Subscriptions, the Created Date column header has a sort arrow. Click to flip between newest-first and oldest-first to spot recent signups or long-tenured customers.

**Transaction History Shortcut.** The Transaction History menu item inside the detail panel takes you to Subscriptions → Payments filtered to that subscription's charges — handy for explaining a billing dispute to a customer.

**Surcharge & Debit Cards.** Ecrypt automatically removes surcharge fees for debit cards (a banner warns you in the Edit Subscription form). Don't try to override this — surcharging debit cards violates card network rules in most US jurisdictions.