Authentication
All subscription management endpoints require a Bearer token in the Authorization header.
Authorization: Bearer <your_jwt_token>
List Subscriptions
Retrieve a paginated list of all subscriptions for the authenticated merchant.
Query Parameters
The page number for pagination.
The number of subscriptions per page. Maximum value is 100.
Filter by subscription status. Accepted values: active, trialing, cancelled, past_due, expired.
Filter by a specific subscription plan ID.
Example Request
curl -X GET "https://olp-api.nipuntheekshana.com/v1/subscriptions?status=active&page=1&limit=10" \
-H "Authorization: Bearer <your_jwt_token>"
Example Response
{
"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
GET /v1/subscriptions/{id}
Path Parameters
The unique identifier of the subscription.
Example Request
curl -X GET "https://olp-api.nipuntheekshana.com/v1/subscriptions/sub_abc123def456" \
-H "Authorization: Bearer <your_jwt_token>"
Example Response
{
"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
POST /v1/subscriptions/{id}/cancel
Path Parameters
The unique identifier of the subscription to cancel.
Example Request
curl -X POST "https://olp-api.nipuntheekshana.com/v1/subscriptions/sub_abc123def456/cancel" \
-H "Authorization: Bearer <your_jwt_token>"
Example Response
{
"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 |
