Skip to main content
The subscriptions module provides tools to view client subscriptions, membership products, and contracts.

Available Tools

list_subscriptions

List client memberships and active subscriptions.
  • Type: Read-only
  • Important Input Fields:
    • clientId (string, optional): Filter subscriptions for a specific client.
    • status (string, optional): Filter by status. Accepted values: Active, Pending, Paused, Cancelled, Failed, Expired, Open, Completed.
    • search (string, optional): Matched against client first name, last name or email. Every matching client in the company is searched.
    • page (integer, optional): Page number.
    • limit (integer, optional): Items per page, default 25, maximum 50.
  • Cancellation information: Each subscription includes cancellationRequest as described below.

get_subscription

Retrieve full details of a specific client subscription.
  • Type: Read-only
  • Important Input Fields:
    • subscriptionId (string, required): Unique identifier for the client’s subscription.
  • Cancellation information: The subscription includes cancellationRequest as described below.

Cancellation information

list_subscriptions and get_subscription return cancellationRequest: null when no cancellation information has been recorded. Otherwise the object contains: Unavailable text fields are empty strings. An existing cancellation record may remain after a subscription is reactivated; use the subscription’s status and dates to determine its current state. The presence of a cancellation reason does not mean a subscription is currently cancelled. Requests awaiting approval are separate from the subscription’s recorded cancellation information. These fields use the existing subscriptions module access and require no new scope or input. Signing data and payment details are not included.

list_membership_action_requests

List membership action requests (cancel, pause, add-ons, change, renew, registration) that need attention, such as pending, failed or rejected requests. Payment-provider details are never returned.
  • Type: Read-only
  • Important Input Fields:
    • status (string, optional): Filter by request status. Accepted values: pending, awaiting_client_signature, client_signed, approved, rejected, applied, failed. Omit to list every request that is not yet applied.
    • clientId (string, optional): Filter requests for a specific client.
    • page (integer, optional): Page number.
    • limit (integer, optional): Items per page.
  • Returns: requestId, clientId, clientName, action, status, membershipName, requestedAt, failedAt and a sanitized failureReason.

list_membership_products

List the company’s catalog of purchasable membership packages.
  • Type: Read-only
  • Important Input Fields:
    • page (integer, optional): Page number.
    • limit (integer, optional): Items per page.

get_membership_change_options

List a member’s active memberships and, for one membership, its cancellation options, cancellation reasons and allowed upgrade/downgrade targets.
  • Type: Read-only
  • Important Input Fields:
    • clientId (string, required): The member.
    • clientProductId (string, optional): The membership to inspect.

Changing subscriptions

The write tools below run the same validation, history entries and approval flows as the coach app. Each needs an explicit write grant for the tool and the coach’s finance permission on the member (Admin by default).

update_subscription_home_location Write

Set the company location for an existing membership and its linked subscription. Use get_membership_change_options to identify the member’s clientProductId. Find an active destination with list_locations in the calendar module or list_client_home_locations in the clients module, when available.
  • Required input: clientId, clientProductId, locationId and userConfirmed: true. Review the member, membership and destination first. Send an idempotency key with the call.
  • Requires an explicit write grant, finance.client_products.update, access to the member and an active destination location in the same company.
  • Returns clientId, clientProductId, locationId, locationName, changed, and subscriptionId when the membership has a linked subscription. When both records already use the selected location, changed is false.
The change applies to future billing. Existing invoices and the home branch on the member’s profile are separate. An inconsistent or ambiguous subscription link must be resolved before the location can be changed.

update_subscription_price Write

  • subscriptionId (string, required), amount (number, required): new price per billing period. Existing invoices are not changed.

change_subscription_billing_date Write

  • subscriptionId (string, required), nextBillingDate (YYYY-MM-DD, required), changeType (next_charge_only or change_billing_anchor, required), reason (string, required).

pause_subscription Write

  • subscriptionId (string, required), pausedUntil (YYYY-MM-DD, future, required). Cancelled, completed, expired or failed subscriptions cannot be paused.

change_subscription_membership Write

Cancel a membership or switch it to another membership.
  • clientId, clientProductId (required): from get_membership_change_options.
  • action (required): cancel, upgrade or downgrade.
  • targetMembershipId: required for upgrade and downgrade.
  • effectiveTiming: immediate, nextTerm (default), afterDays, nextMonth or manualDate, with delayDays or requestedEndDate where needed.
  • reasonCode, reasonText, message: cancellation reason and internal note.
  • paymentMethod: for a paid switch.
When the membership requires approval, an approval request is created and the response has approvalRequested: true. Memberships that require a signature for the change are rejected.

decide_membership_action_request Write

Approve or reject one pending membership action request (sign-up, change, pause or cancellation) from list_membership_action_requests, like the dashboard. Before approving, call with decision approve and preview true: the result shows any back-billing (count, total) and a billingPreview.fingerprint. Show that to the coach, then approve with the same billingPreviewFingerprint; a changed quote is rejected. Reject may refund an initial payment per company rules. Get explicit coach confirmation for the final call.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • requestId (string, required)
    • decision (string: approve, reject, required)
    • preview (boolean, optional)
    • billingPreviewFingerprint (string, optional)
    • reviewMessage (string, optional)
    • idempotencyKey (string, optional)

create_subscription Write

Start a membership for one member with the dashboard rules. First call with preview true: it returns the start amounts and a quoteFingerprint. Show the coach the price, start date, first charge and pay-now amount, then call again with preview false and that quoteFingerprint. paymentMethod LinkAuto/LinkManual sends a payment link, Paid marks the first payment as paid, Free charges nothing. SEPA direct debit and memberships that require a member signature must be sold in the dashboard. If the membership has registration terms, legalAccepted must confirm the member accepted them.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • clientId (string, required)
    • membershipProductId (string, required)
    • preview (boolean, required)
    • quoteFingerprint (string, optional)
    • paymentMethod (string: LinkAuto, LinkManual, Paid, Free, required)
    • productPrice (number, required)
    • startDate (string, optional)
    • firstChargeDate (string, optional)
    • homeLocationId (string, optional)
    • internalNote (string, optional)
    • legalAccepted (boolean, optional)
    • idempotencyKey (string, optional)

cancel_subscription Write

End one member’s membership like the dashboard: endDate today or earlier ends it now (future credits expire), a later endDate stops auto-renewal and ends it on that date. Use clientProductId from get_subscription. Contract minimum terms are enforced by the app. reasonText is stored as the cancellation reason. The member gets the normal cancellation email unless suppressEmail is true. Show the coach the membership, end date and effect, and get explicit confirmation first.
  • Type: Write (requires userConfirmed: true and the write-tool grant)
  • Input Fields:
    • clientId (string, required)
    • clientProductId (string, required)
    • endDate (string, required)
    • reasonText (string, optional)
    • suppressEmail (boolean, optional)
    • idempotencyKey (string, optional)

Natural Language Examples

  • “Does client client_5f81 have an active membership subscription?”
  • “List all membership products we sell.”
  • “Show the recorded reasons why members cancelled their subscriptions.”

JSON-RPC Call Example (list_subscriptions)