Subscriptions API

Manage subscriber subscriptions.

Endpoints

GET/api/v1/subscriptions

List all subscriptions (paginated)

Query Parameters:

Param	Type	Default	Description
limit	integer	50	Items per page (1–200)
offset	integer	0	Items to skip
status	string	—	Filter by status (active, paused, cancelled, etc.)

Response:

{
  "items": [
    {
      "id": "sub_abc123",
      "plan_id": "plan_xyz",
      "subscriber_id": "usr_456",
      "status": "active",
      "current_period_start": 1704067200,
      "current_period_end": 1706745600,
      "created_at": 1704067200
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

---

GET/api/v1/subscriptions/{id}

Get subscription details

---

POST/api/v1/subscriptions/{id}/pause

Pause a subscription

Stops future billing. Access continues until current period ends.

---

POST/api/v1/subscriptions/{id}/resume

Resume a paused subscription

---

POST/api/v1/subscriptions/{id}/cancel

Cancel a subscription immediately

⚠️

Cancellation is immediate and notifies the subscriber. Use pause if you want them to keep access until period end.

---

POST/api/v1/subscriptions/{id}/extend

Add free days to a subscription

Query Parameters:

Param	Type	Description
days	integer	Number of days to add

---

GET/api/v1/subscriptions/{id}/manage-link

Get subscriber's self-service portal URL

Response:

{
  "subscription_id": "sub_abc123",
  "subscriber_email": "user@example.com",
  "manage_url": "https://your-lnbits.com/subscriptions_manager/manage?token=abc123"
}

Subscription Statuses

Status	Description
pending	Waiting for first payment
active	Paid and current
paused	Temporarily suspended
past_due	Payment failed, in grace period
payment_failed	Grace period ended
cancelled	Manually cancelled
expired	Period ended

Example: Check if Active

import requests

def is_subscription_active(sub_id):
    response = requests.get(
        f"https://your-lnbits.com/subscriptions_manager/api/v1/subscriptions/{sub_id}",
        headers={"X-Api-Key": "YOUR_INVOICE_KEY"}
    )

    subscription = response.json()
    return subscription["status"] == "active"

def list_active_subscriptions():
    response = requests.get(
        "https://your-lnbits.com/subscriptions_manager/api/v1/subscriptions",
        headers={"X-Api-Key": "YOUR_INVOICE_KEY"},
        params={"status": "active", "limit": 100}
    )

    data = response.json()
    return data["items"]  # PaginatedResponse — items is the list

# Usage
if is_subscription_active("sub_abc123"):
    print("Subscription is active")