# Subscription Lifecycle

The subscription lifecycle defines how a subscriber progresses from initial purchase through renewals, failed payments, cancellations, and potential reactivation. Zotlo manages all billing logic, dates, retries, and status transitions, while your application decides how user access is handled.

## **Subscription Start**

A subscription begins the moment a user completes a checkout flow, either through Embedded Checkout, Hosted Checkout, Quiz Funnels, or API-generated checkout links.

When a subscription is created:

* A subscriber record is created
* The initial plan, pricing, currency, and billing cycle are locked in
* Payment method is attached (cards, Apple Pay, Google Pay, PayPal, or PSP token)
* State become **trial** (if the plan includes a trial) or **paid** (if no trial)
* Status become **active**
* If plan has a trial, first paid renewal is scheduled for the end of the trial
* If plan has no trial, first renewal is scheduled based on billing interval
* `start_date`, `expire_date`, and other lifecycle timestamps are calculated

{% hint style="info" %}
A subscription only enters the lifecycle once the first successful payment (or successful trial start) is recorded.
{% endhint %}

## **Recurring Billings**

At the end of billing cycles, Zotlo attempts to charge the saved payment method.

If the renewal succeeds:

* Status stays **active**
* A new cycle begins
* `expire_date` is recalculated

## **Dunning & Grace**

When a renewal fails, Zotlo begins an automated retry process designed to recover involuntary churn. Grace Period is 30 days by default. It gives subscribers time to update their payment method after failed renewal attempts.

During grace:

* Status = **grace**
* Zotlo apply smart retries 
* No new charges happen unless a retry succeeds

If a retry succeeds:

* Status returns to **active**
* Billing returns to normal

If all retries fail:

* The subscription moves into the **cancellation stage**

{% hint style="info" %}
**Access rules during grace are fully controlled by your application.**\
You may allow full access, partial access, or block access entirely.
{% endhint %}

## **Cancellations**

Subscriptions may be canceled by:

* The user (via Customer Portal)
* The merchant (Dashboard / API)
* Zotlo (automatically when grace period ends and recovery fails)

When a subscription is canceled:

* **Status immediately becomes `canceled`**
* **expire\_date does not change**
* No further renewal attempts occur

{% hint style="info" %}
**Access After Cancellation**

Zotlo does not block or allow access automatically.

Your application decides:

* Whether users retain access until the expire\_date, or
* Whether access is removed immediately after cancellation
  {% endhint %}

## **Reactivations**

A canceled subscription can be reactivated if the **expire\_date has not passed**.

Reactivation behavior:

* No additional charge is made immediately
* Status becomes **active** again
* The subscription continues until the existing `expire_date`
* On the next renewal attempt, normal billing behavior resumes

Reactivation is **not possible** after `expire_date` has passed.

## **Price & Currency Changes**

Price and currency updates affect **future renewals**, not historical charges.

* Existing subscriptions continue with their current price at the next billing cycle
* Past invoices remain unchanged
* If you want existing subscribers to move to a new price, this can be adjusted by Zotlo