Skip to main content

​
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

AspectActiveIncomplete
Payment StatusCurrent period paidPayment pending
Feature Access✅ Full access✅ Full access
Query PriorityHighestHighest (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

AspectIncompleteExpired
Feature Access✅ Full access❌ No access
Can Pay?✅ Yes, to activate❌ No, must renew
RecoveryComplete paymentCreate new subscription or renew
Grace PeriodWithin configured durationPast 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.