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

# Understanding Subscription Incomplete Status

> Learn about the Incomplete status, its configuration, and how it affects your subscriptions

# Understanding Subscription Incomplete Status

## What is Incomplete Status?

The **Incomplete** status is a special subscription state that indicates a subscription has been created but payment has not been completed yet. This status provides a **grace period** for customers to complete payment while still allowing them to use subscription features.

**Key Concept:** Unlike `Pending` or `Expired` statuses, subscriptions in `Incomplete` status are treated as **valid active subscriptions** in most business scenarios, meaning customers can continue to access their plan features during this period.

***

## When Does a Subscription Enter Incomplete Status?

Subscriptions can enter `Incomplete` status in the following scenarios:

### 1. Subscription Renewal Payment Failed

**Scenario:** When a subscription's billing cycle ends but the automatic payment fails or hasn't been processed yet.

**Example:**

* Customer has a **Monthly Pro Plan** (\$99/month)
* Billing cycle: January 1 - January 31, 2025
* On **January 31, 2025** (period end), automatic payment fails (insufficient funds, expired card, etc.)
* **Result:** Subscription automatically transitions to `Incomplete` status
* Customer can still access Pro Plan features during the grace period
* System waits for the configured duration (default: 24 hours) for payment to be completed

### 2. Trial Period Ends Without Payment

**Scenario:** When a trial subscription ends and the first payment hasn't been processed.

**Example:**

* Customer signs up for a **14-day trial** starting January 1, 2025
* Trial ends on **January 15, 2025**
* Customer hasn't provided payment method or payment fails
* **Result:** Subscription transitions to `Incomplete` status
* Customer retains access while they complete payment setup

### 3. Create Subscription with "Start Incomplete" Option

**Scenario:** When creating a subscription with the `startIncomplete` flag set to `true`.

**Example:**

* You want to allow customers to **start using the service immediately** but pay later
* Create subscription with `startIncomplete: true`
* **Result:**
  * Subscription starts in `Incomplete` status
  * Customer can immediately access all plan features
  * Invoice is generated but payment can be completed later
  * Perfect for "Buy now, pay later" scenarios

### 4. Admin Temporary Activation

**Scenario:** When an admin manually activates a subscription temporarily through the admin portal.

**Example:**

* Customer's payment is delayed due to bank processing
* Admin temporarily activates the subscription to maintain service continuity
* **Result:** Subscription is set to `Incomplete` status
* Customer can use the service while completing payment

### 5. Wire Transfer Processing

**Scenario:** When a subscription uses wire transfer payment method and is waiting for offline verification.

**Example:**

* Customer chooses wire transfer payment
* Subscription is in `Processing` status waiting for payment confirmation
* Admin can mark subscription as temporarily valid
* **Result:** Subscription transitions to `Incomplete` status while awaiting payment verification

***

## How Incomplete Status Works

### Grace Period Behavior

Once a subscription enters `Incomplete` status, the system provides a **grace period** based on your configuration:

**Default Grace Period:** 24 hours (86,400 seconds)

**During the grace period:**

* ✅ Customer retains access to all subscription features
* ✅ Subscription is treated as "active" in queries and business logic
* ✅ Customer can update, renew, or modify the subscription
* ✅ System allows the customer to complete payment
* ⏱️ Timer starts counting down from the configured duration

### Expiration Logic

If payment is not completed within the grace period, the subscription will expire.

**Expiration Calculation:**

```
Expiration Time = max(Period End, Trial End) + Incomplete Status Duration
```

**Example:**

* Period ends: **January 31, 2025 00:00:00**
* Incomplete Status Duration: **24 hours** (86,400 seconds)
* Expiration time: **February 1, 2025 00:00:00**
* If payment is not completed by February 1, 2025, subscription becomes `Expired`

***

## Configuration: Incomplete Status Duration

### Default Value

* **Default:** 86,400 seconds (24 hours)
* **Location:** Go to **Configuration** → **Subscription Config** page
* **Field:** `Incomplete Status Duration` (in seconds)

### How to Configure

1. Navigate to **Configuration** → **Subscription Config**
2. Find the **Incomplete Status Duration** field
3. Enter the duration in seconds
4. Click **Save**

**Common Duration Values:**

* **1 hour:** `3600` seconds
* **24 hours (default):** `86400` seconds
* **3 days:** `259200` seconds
* **7 days:** `604800` seconds

### Configuration Rules

⚠️ **Important Threshold:**

* If you set `Incomplete Status Duration` to **30 seconds or less**, the system will **NOT automatically** convert unpaid subscriptions to `Incomplete` status
* This means subscriptions will go directly to `Expired` status after period ends
* **Recommendation:** Keep duration above 30 seconds for grace period functionality

***

## Examples and Use Cases

### Example 1: Payment Failure Recovery

**Scenario:**

* Customer's credit card expires and automatic payment fails
* Subscription period ends on **January 31, 2025**

**Timeline:**

1. **January 31, 00:00** - Period ends, payment fails
2. **January 31, 00:00** - Subscription → `Incomplete` status
3. **January 31, 08:00** - Customer receives payment failure notification email
4. **January 31, 10:00** - Customer updates payment method
5. **January 31, 10:05** - Customer completes payment
6. **January 31, 10:05** - Subscription → `Active` status ✅

**Result:** Customer experienced only 10 hours of service interruption risk, but never lost access.

### Example 2: Extended Grace Period

**Scenario:** Your business wants to give customers 3 days to resolve payment issues.

**Configuration:**

* Set `Incomplete Status Duration` to **259,200 seconds** (3 days)

**Timeline:**

* **Day 1 (Jan 31):** Period ends, subscription → `Incomplete`
* **Day 2 (Feb 1):** Customer receives reminders, still has access
* **Day 3 (Feb 2):** Customer resolves payment issue, subscription → `Active`
* If not resolved by **Day 4 (Feb 3):** Subscription → `Expired`

**Benefit:** More time for customers to resolve payment issues, reducing involuntary churn.

### Example 3: Buy Now, Pay Later

**Scenario:** Allow customers to start using service immediately while payment processes.

**Setup:**

* Create subscription with `startIncomplete: true`
* Set `Incomplete Status Duration` to **7 days** (604,800 seconds)

**Timeline:**

* **Day 1:** Customer signs up, subscription created in `Incomplete` status
* **Day 1-7:** Customer has full access to all features
* **Day 3:** Invoice is generated and sent to customer
* **Day 5:** Customer completes payment → Subscription → `Active` ✅
* If not paid by **Day 8:** Subscription → `Expired`

**Benefit:** Improves conversion rates by allowing immediate access.

### Example 4: Wire Transfer Processing

**Scenario:** Enterprise customer prefers wire transfer payment.

**Timeline:**

1. **January 15:** Customer subscribes, chooses wire transfer
2. **January 15:** Subscription → `Processing` status
3. **January 16:** Admin temporarily activates → Subscription → `Incomplete`
4. **January 16-18:** Customer has access while bank processes payment
5. **January 18:** Admin verifies payment received, marks invoice as paid
6. **January 18:** Subscription → `Active` status ✅

**Benefit:** Maintains service continuity during offline payment processing.

***

## Incomplete vs Other Statuses

### Incomplete vs Active

| Aspect             | Active              | Incomplete               |
| ------------------ | ------------------- | ------------------------ |
| **Payment Status** | Current period paid | Payment pending          |
| **Feature Access** | ✅ Full access       | ✅ Full access            |
| **Query Priority** | Highest             | Highest (same as Active) |
| **Can Renew?**     | ✅ Yes               | ✅ Yes                    |
| **Can Update?**    | ✅ Yes               | ✅ Yes                    |

**Key Point:** Both `Active` and `Incomplete` are treated as **valid subscriptions** in business logic.

### Incomplete vs Expired

| Aspect             | Incomplete                 | Expired                          |
| ------------------ | -------------------------- | -------------------------------- |
| **Feature Access** | ✅ Full access              | ❌ No access                      |
| **Can Pay?**       | ✅ Yes, to activate         | ❌ No, must renew                 |
| **Recovery**       | Complete payment           | Create new subscription or renew |
| **Grace Period**   | Within configured duration | Past grace period                |

***

## Status Transitions

### Entering Incomplete Status

```
Active/Pending/Processing
    ↓
[Trigger: Payment failed / Period ended / Admin action]
    ↓
Incomplete Status
```

### Exiting Incomplete Status

**Path 1: Payment Success**

```
Incomplete
    ↓
[Customer completes payment]
    ↓
Active ✅
```

**Path 2: Expiration**

```
Incomplete
    ↓
[Grace period expires]
    ↓
Expired ❌
```

***

## Business Benefits

### 1. Reduced Involuntary Churn

By providing a grace period, you reduce customers lost due to temporary payment issues:

* Expired credit cards
* Insufficient funds (temporary)
* Bank processing delays
* Payment method updates

### 2. Improved Customer Experience

Customers maintain service continuity while resolving payment issues:

* No immediate service interruption
* Time to update payment information
* Opportunity to complete payment without disruption

### 3. Flexible Payment Models

Support various business models:

* Buy now, pay later
* Enterprise wire transfers
* Manual payment verification
* Temporary activations

***

## Best Practices

### 1. Duration Recommendations

* **SaaS Services:** 24-72 hours (allows time for payment updates)
* **High-Value Services:** 3-7 days (for enterprise customers)
* **Low-Value Services:** 12-24 hours (faster resolution)

### 2. Communication

* Send payment failure notifications immediately
* Remind customers during grace period
* Provide clear instructions for payment completion

### 3. Monitoring

* Track incomplete subscription counts
* Monitor conversion rates from incomplete to active
* Analyze expiration reasons

### 4. Configuration

* Never set duration below 30 seconds (disables auto-incomplete)
* Match duration to your business model
* Consider payment method processing times

***

## Configuration in Admin Portal

To configure Incomplete Status Duration:

1. Log in to your UniBee Admin Portal
2. Navigate to **Configuration** → **Subscription Config**
3. Find **Incomplete Status Duration**
4. Enter duration in seconds:
   * **3600** = 1 hour
   * **86400** = 24 hours (default)
   * **259200** = 3 days
   * **604800** = 7 days
5. Click **Save** to apply changes

**Note:** Changes apply to all new incomplete subscriptions. Existing incomplete subscriptions use the duration that was active when they entered incomplete status.

***

## Related Documentation

* [Subscription Status Overview](/documentation/subscription/status) - Learn about all subscription statuses
* [Subscription Configuration](/documentation/subscription/subscription_configs) - General subscription settings
* [Subscription Auto-Charge Workflow](/documentation/subscription/subscription-auto-charge-workflow) - How automatic payments work