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

# Manage Subscriptions

> List, view, and cancel subscriptions

## Authentication

All subscription management endpoints require a **Bearer token** in the `Authorization` header.

```
Authorization: Bearer <your_jwt_token>
```

***

## List Subscriptions

<Card>
  `GET /v1/subscriptions`
</Card>

Retrieve a paginated list of all subscriptions for the authenticated merchant.

### Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number for pagination.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  The number of subscriptions per page. Maximum value is `100`.
</ParamField>

<ParamField query="status" type="string">
  Filter by subscription status. Accepted values: `active`, `trialing`, `cancelled`, `past_due`, `expired`.
</ParamField>

<ParamField query="planId" type="string">
  Filter by a specific subscription plan ID.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://olp-api.nipuntheekshana.com/v1/subscriptions?status=active&page=1&limit=10" \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Example Response

```json theme={null}
{
  "subscriptions": [
    {
      "id": "sub_abc123def456",
      "planId": "plan_abc123def456",
      "planName": "Pro Monthly",
      "customerEmail": "alice@example.com",
      "customerName": "Alice Johnson",
      "status": "active",
      "currentPeriodStart": "2026-03-26T14:30:00Z",
      "currentPeriodEnd": "2026-04-26T14:30:00Z",
      "createdAt": "2026-03-12T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}
```

***

## Get Subscription Details

<Card>
  `GET /v1/subscriptions/{id}`
</Card>

Retrieve the full details of a specific subscription.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subscription.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://olp-api.nipuntheekshana.com/v1/subscriptions/sub_abc123def456" \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Example Response

```json theme={null}
{
  "id": "sub_abc123def456",
  "planId": "plan_abc123def456",
  "planName": "Pro Monthly",
  "amount": 29.99,
  "currency": "USD",
  "interval": "monthly",
  "customerEmail": "alice@example.com",
  "customerName": "Alice Johnson",
  "walletAddress": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
  "status": "active",
  "currentPeriodStart": "2026-03-26T14:30:00Z",
  "currentPeriodEnd": "2026-04-26T14:30:00Z",
  "trialEnd": null,
  "cancelledAt": null,
  "createdAt": "2026-03-12T14:30:00Z"
}
```

***

## Cancel Subscription

<Card>
  `POST /v1/subscriptions/{id}/cancel`
</Card>

Cancel an active subscription. The subscription remains active until the end of the current billing period.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subscription to cancel.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://olp-api.nipuntheekshana.com/v1/subscriptions/sub_abc123def456/cancel" \
  -H "Authorization: Bearer <your_jwt_token>"
```

### Example Response

```json theme={null}
{
  "id": "sub_abc123def456",
  "status": "cancelled",
  "cancelledAt": "2026-03-26T15:00:00Z",
  "currentPeriodEnd": "2026-04-26T14:30:00Z",
  "message": "Subscription cancelled. Access remains active until the end of the current billing period."
}
```

## Subscription Statuses

| Status      | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `active`    | The subscription is active and payments are being collected  |
| `trialing`  | The subscription is in its free trial period                 |
| `past_due`  | A renewal payment failed; the system will retry              |
| `cancelled` | The subscription has been cancelled; active until period end |
| `expired`   | The subscription has fully expired after cancellation        |