Skip to main content
GHL MCP Guide
SBN

Subscriptions

Payments & Billing · Intermediate · Updated March 2026

List and retrieve subscription records with billing cycles, amounts, renewal dates, and lifecycle status monitoring.

Subscriptions gives you visibility into all recurring billing relationships in a GHL sub-account. Monthly retainers, annual plans, membership dues — every active, paused, or cancelled subscription is accessible here.

What This MCP Tool Does

This tool retrieves subscription records with billing cycle details, amounts, renewal dates, and current status. Monitor active subscriptions for revenue forecasting, detect cancellations early for retention outreach, and track the health of recurring revenue.

Endpoint Reference

List subscriptions: GET /payments/subscriptions Retrieve all subscription records with filtering and pagination.

Get subscription by ID: GET /payments/subscriptions/{subscriptionId} Retrieve full details for a specific subscription.

Authentication

Requires a Private Integration Token (PIT) with the payments scope enabled.

Key Parameters

Subscription records include:

  • id — unique subscription identifier
  • contactId — the subscribing customer
  • amount — recurring charge amount
  • currency — currency code
  • interval — billing frequency (monthly, yearly, etc.)
  • status — current state (active, paused, cancelled, past_due)
  • currentPeriodStart, currentPeriodEnd — current billing cycle dates
  • cancelledAt — cancellation timestamp if applicable

Important Notes

Subscription management (creation, pausing, cancellation) typically happens through the checkout flow, GHL UI, or payment processor. This API provides read access for monitoring and integration purposes.

For agencies tracking MRR (Monthly Recurring Revenue) across client accounts, this endpoint is essential. Sum active subscription amounts to calculate current MRR per location or across the agency.

Past-due subscriptions indicate payment failures. Combine with Contact CRUD to identify the affected customers and trigger dunning workflows through Campaign & Workflow.

Common Questions

Can I cancel or pause a subscription through the API? Check the endpoint documentation for write capabilities. Subscription lifecycle management may require the GHL UI or direct payment processor API calls.

How do I detect subscription cancellations in real-time? Poll the subscription endpoint on a schedule and compare against previous results. Alternatively, configure GHL webhooks to fire on subscription status changes and process them through an external system.

How do I calculate churn rate? Track cancellations over time against total active subscriptions. Pull subscription data periodically and compare the cancelled count to the total count for churn percentage.

Back to GHL MCP Guide