Service plans
Service plans in the BlueSuite REST API
A service plan defines recurring billing and optional visits. Creating or editing a plan does not subscribe or charge a customer.
Billing cadence and visit cadence are independent. Use no_appointments: true for billing-only plans. A fixed_end_date duration requires duration_end_date, including when updating or activating an existing plan. Status is draft, active, or archived.
For existing customers enrolled in a plan, use Service-plan subscriptions.
GET /api/v1/service-plans
GET /api/v1/service-plansRequired scopes: service_plans:read.
Query parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
page | integer | No | Page number, starting at 1. Default: 1. |
per_page | integer | No | Records per page, from 1 to 100. Default: 25. minimum: 1. maximum: 100. |
search | string | No | Search text. maxLength: 100. |
sort_by | string | No | Sort column. See the supported columns below when listed. |
sort_direction | "asc", "desc" | No | Sort direction. Default: "desc". |
status | string | No | Filter by status. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/service-plans
POST /api/v1/service-plansRequired scopes: service_plans:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
name | string | Yes | minLength: 1. |
description | string or null | No | |
billing_amount | number | No | Default: 0. minimum: 0. |
billing_cycle | "weekly", "monthly", "quarterly", "semi_annually", "annually" | No | Default: "monthly". |
billing_timing | "start", "end" | No | Default: "start". |
duration_type | "until_cancelled", "fixed_end_date" | No | Default: "until_cancelled". |
duration_end_date | string or null | No | |
visit_recurrence_frequency | integer | No | Default: 1. |
visit_recurrence_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "monthly". |
visit_recurrence_schedule | JSON value or null | No | |
no_appointments | boolean | No | Default: false. |
tax_rate | number | No | Default: 0. minimum: 0. |
tax_rate_id | integer or null | No | |
terms | string or null | No | |
default_account_manager_id | string or null | No | |
addons | JSON value or null | No | |
status | "draft", "active", "archived" | No | Default: "draft". |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
201 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
GET /api/v1/service-plans/:id
GET /api/v1/service-plans/:idRequired scopes: service_plans:read.
Path parameters: id. Use positive integer record IDs from this workspace.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/service-plans/:id
PUT /api/v1/service-plans/:idRequired scopes: service_plans:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
name | string | No | minLength: 1. |
description | string or null | No | |
billing_amount | number | No | Default: 0. minimum: 0. |
billing_cycle | "weekly", "monthly", "quarterly", "semi_annually", "annually" | No | Default: "monthly". |
billing_timing | "start", "end" | No | Default: "start". |
duration_type | "until_cancelled", "fixed_end_date" | No | Default: "until_cancelled". |
duration_end_date | string or null | No | |
visit_recurrence_frequency | integer | No | Default: 1. |
visit_recurrence_unit | "daily", "weekly", "monthly", "yearly", "custom", "forever", "occurrences" | No | Default: "monthly". |
visit_recurrence_schedule | JSON value or null | No | |
no_appointments | boolean | No | Default: false. |
tax_rate | number | No | Default: 0. minimum: 0. |
tax_rate_id | integer or null | No | |
terms | string or null | No | |
default_account_manager_id | string or null | No | |
addons | JSON value or null | No | |
status | "draft", "active", "archived" | No | Default: "draft". |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
DELETE /api/v1/service-plans/:id
DELETE /api/v1/service-plans/:idRequired scopes: service_plans:write.
Path parameters: id. Use positive integer record IDs from this workspace.
No request body.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/service-plans/:id/status
PUT /api/v1/service-plans/:id/statusRequired scopes: service_plans:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
status | "draft", "active", "archived" | Yes |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.