# 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](/integrating-zotlo/api-reference/introduction.md). It provides a full operational view of every subscription and its events.

<div data-with-frame="true"><figure><img src="/files/MouLmsPTjJmkZEJPJoEd" 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](/features/subscriptions/plan-changes.md))

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zotlo.com/features/customer-management/managing-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.