# Managing Subscriptions

The **Subscriptions** section lets you track all subscribers across your projects, review lifecycle states, manage cancellations, inspect billing history, and access payment logs in [Zotlo Dashboard](https://console.zotlo.com) or via [Zotlo API](https://docs.zotlo.com/integrating-zotlo/api-reference/introduction). It provides a full operational view of every subscription and its events.

<div data-with-frame="true"><figure><img src="https://1742217996-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmO4aHbmqkCcIAsvfoviI%2Fuploads%2F7HLbnr1f14yFgn9RtoaI%2FScreenshot%202026-03-03%20at%2010.08.50.png?alt=media&#x26;token=4355e89d-ac30-4631-9dc3-122e2c3febb6" alt="" width="563"><figcaption></figcaption></figure></div>

## **Subscriptions Overview**

Navigate to your project in **Zotlo Dashboard → Subscriptions** to view an aggregated list of all active, grace, and canceled subscriptions.

For each subscription, the list view shows:

* Subscriber ID
* Plan & billing interval
* Status
* Country
* Start & expire dates
* Latest renewal outcome
* Payment method

## **Subscription Details**

Click any subscriber to open the **Subscription Detail** page. The page includes three major sections:

### **Summary**

* Current **status** (active / grace / canceled)
* start\_date, expire\_date
* Next renewal attempt (if applicable)
* Currency & pricing info
* Trial information (if applicable)
* Linked payment method (card / wallet / PSP)

### **Transactions**

Shows all subscription events:

* Initial purchase
* Trial start & trial end
* Successful renewals
* Failed renewals
* Grace period transitions
* Cancellation events
* Reactivations

Each event links to its corresponding payment (if a payment exists).

### **Payment Logs**

A chronological log of all attempted, failed and successful charges, including:

* Retry attempts
* Error codes
* Timestamp of each attempt

This helps diagnose payment issues and involuntary churn.

## **Subscription States**

Each subscription has a **state** that reflects whether the subscriber is in a trial period or in a paid billing cycle. This is separate from the *status* (active, grace, canceled).

**Trial**\
The subscriber is currently in a trial period. This only indicates the phase of the subscription, not whether the subscription is active or passive.

**Paid**\
The subscriber is currently in a paid billing cycle. This also only reflects the billing phase and does not indicate subscription status.

{% hint style="info" %}
**Important Notes**

* A subscription transitions from **trial → paid only after the first renewal payment succeeds**
* State changes do not affect access behavior, your application determines how access is granted.
* State is always visible in subscription details and is included in webhook payloads.
  {% endhint %}

## **Subscription Statuses**

### **Active**

Subscription is fully valid. Next renewal is scheduled. This means the subscription is in a **paid** billing cycle with a successfully captured payment. The subscriber has full entitlement to the service.

### **Passive/Canceled**

Subscription has ended.

* No further renewals are attempted
* expire\_date remains unchanged
* Access rules depend on your app (you may allow or block access until expire\_date)

### **Grace**

Renewal has failed and the subscription is in the retry (dunning) period.

* Grace period lasts 30 days by default
* Retry schedule: **day 1, 2, 3, 5, 8, 13, 20, 30**
* If none succeed, status becomes **canceled**

{% hint style="info" %}
Your application decides whether **users have access during grace**.
{% endhint %}

## **Managing Subscriptions**

From the Subscription Detail page or via API, you can:

### **Cancel a Subscription**

Status becomes **canceled** immediately, but the user may continue to access the service until `expire_date`. Access rules are fully controlled by your application.

### **Pause a Subscription**

* Status becomes paused instantly
* No renewals occur while paused
* `expire_date` and existing paid time remain unchanged

### **Reactivate a Subscription**

A paused or canceled subscription can be reactivated **as long as expire\_date has not passed**:

* No immediate charge
* Status becomes active
* Renewal resumes at next scheduled cycle

## **Refund a Charge**

You can issue full or partial refunds. Refund actions include selecting the specific charge, choosing the refund amount, and submitting a reason for audit and reporting purposes.

## **Change Plans**

You can apply plan upgrades, downgrades, billing interval changes, or pricing adjustments to any active subscription. For detailed behavior and examples, see the [Plan Changes](https://docs.zotlo.com/features/subscriptions/plan-changes))

{% hint style="info" %}
You can handle all subscription operations, cancellations, pauses, reactivations, and plan changes from the Dashboard or via the API.
{% endhint %}