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
cancellationRequestas 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
cancellationRequestas 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 yetapplied.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,failedAtand a sanitizedfailureReason.
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,locationIdanduserConfirmed: 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, andsubscriptionIdwhen the membership has a linked subscription. When both records already use the selected location,changedis false.
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_onlyorchange_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): fromget_membership_change_options.action(required):cancel,upgradeordowngrade.targetMembershipId: required forupgradeanddowngrade.effectiveTiming:immediate,nextTerm(default),afterDays,nextMonthormanualDate, withdelayDaysorrequestedEndDatewhere needed.reasonCode,reasonText,message: cancellation reason and internal note.paymentMethod: for a paid switch.
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: trueand 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: trueand 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: trueand 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.”