Service Plans
BlueSuite MCP tools for service plans
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List the recurring service plans the business offers, maintenance agreements, seasonal packages. These are templates customers subscribe to, not the subscriptions themselves.
| Field | Type / accepted values | Required | Details |
|---|
status | array of "draft", "active", "archived" | No | Filter by draft, active or archived. |
search | string | No | Search by plan name. |
page | integer | No | |
per_page | integer | No | minimum: 1. maximum: 100. |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Get one service plan with its pricing, billing cycle and visit schedule.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Service plan ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Create a recurring service plan customers can subscribe to. This defines the offer, price, how often it bills, how often visits happen, and bills nobody by itself. New plans start as drafts; publish with update_service_plan_status. Note billing cycle and visit frequency are independent: a plan can bill monthly and visit quarterly.
| Field | Type / accepted values | Required | Details |
|---|
name | string | Yes | e.g. "Annual HVAC Maintenance". |
description | string | No | |
billing_amount | number | No | Charged each billing cycle. |
billing_cycle | "weekly", "monthly", "quarterly", "semi_annually", "annually" | No | How often the customer is charged. Default: monthly. |
billing_timing | "start", "end" | No | Charge at the 'start' or 'end' of each cycle. Default: start. |
duration_type | "until_cancelled", "fixed_end_date" | No | 'until_cancelled' or 'fixed_end_date'. Default: until_cancelled. |
duration_end_date | string | No | Required when duration_type is 'fixed_end_date' (YYYY-MM-DD). |
visit_recurrence_frequency | integer | No | How many visit_recurrence_units between visits. Default: 1. |
visit_recurrence_unit | "daily", "weekly", "monthly", "yearly", "custom" | No | Unit for the visit schedule. Default: monthly. |
no_appointments | boolean | No | A billing-only plan: subscribers are charged but no visits are booked. |
tax_rate | number | No | |
tax_rate_id | integer | No | Tax rate preset ID. |
terms | string | No | Terms shown to the customer. |
default_account_manager_id | string | No | UUID of the default account manager. Use list_users to resolve a name. |
status | "draft", "active", "archived" | No | Default: draft. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update a service plan. Send only what changes, the server merges it over the existing plan. Changing the price affects new subscribers; anyone already subscribed keeps billing at the terms they signed up under, since their charge lives in Stripe.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Service plan ID |
name | string | No | |
description | string | No | |
billing_amount | number | No | |
billing_cycle | "weekly", "monthly", "quarterly", "semi_annually", "annually" | No | |
billing_timing | "start", "end" | No | |
duration_type | "until_cancelled", "fixed_end_date" | No | |
duration_end_date | string | No | |
visit_recurrence_frequency | integer | No | |
visit_recurrence_unit | "daily", "weekly", "monthly", "yearly", "custom" | No | |
no_appointments | boolean | No | |
tax_rate | number | No | |
tax_rate_id | JSON value | No | |
terms | string | No | |
default_account_manager_id | string | No | UUID of the default account manager. Use list_users to resolve names. Format: uuid. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Publish, unpublish or archive a service plan. This is the template's own status: archiving a plan stops new signups but does NOT cancel or stop billing anyone already subscribed to it.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Service plan ID |
status | "draft", "active", "archived" | Yes | draft (not offered), active (open for signups), archived (retired). |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete a service plan. Archive it instead if anyone has ever subscribed, archiving stops new signups and keeps the history.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Service plan ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
List customers subscribed to service plans, with their status and billing amount. Use this to answer who is on a plan, who is paused, and who cancelled.
| Field | Type / accepted values | Required | Details |
|---|
service_plan_id | integer | No | Only subscribers to this plan. |
status | array of "pending", "active", "paused", "cancelled", "expired" | No | Filter by pending, active, paused, cancelled or expired. |
page | integer | No | |
per_page | integer | No | minimum: 1. maximum: 100. |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Get one subscription with its plan, customer, status and billing details.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Subscription ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Reassign a subscription: which client it belongs to, which property it covers, or who manages the account. Price and billing cadence cannot be changed here, those live on the plan and in Stripe, and editing them in BlueSuite alone would disagree with what the customer is actually charged. There is also no way to CREATE a subscription from here: signing someone up requires collecting a payment method, which has to happen in the dashboard.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Subscription ID |
contact_id | JSON value | No | Client the subscription belongs to. |
property_id | JSON value | No | Property it covers. |
account_manager_id | string | No | UUID of the account manager. Use list_users to resolve a name. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Cancel a customer's service plan subscription and stop billing them. This cancels the Stripe subscription first, then marks it cancelled in BlueSuite, doing only the second would leave the customer being charged every cycle. If Stripe refuses, nothing is changed and an error comes back; report that to the user rather than assuming billing stopped. Confirm with the user before calling: this stops a recurring payment.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Subscription ID to cancel. |
force | boolean | No | Mark it cancelled in BlueSuite even if Stripe could not be cancelled. Leaves the customer being billed, only use when the user understands that and asks for it. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.