Service-plan subscriptions
Service-plan subscriptions in the BlueSuite REST API
Read existing customer subscriptions, change their contact/property/account manager, or cancel them. Public v1 does not provide subscription creation, pricing edits, or a general subscription status setter. Enrollment uses the customer portal or dashboard flow.
Cancellation and billing
Use POST /service-plan-subscriptions/:id/cancel. For Stripe-backed subscriptions, the endpoint cancels Stripe billing before marking the BlueSuite subscription cancelled. A missing connection returns 409; a failed Stripe cancellation returns 502, leaving the subscription active.
force: true permits a BlueSuite-only cancellation when billing cannot be stopped. It can leave Stripe charging the customer. Only use it when that consequence is intended. Check billing_stopped and stripe_cancelled in the result. Already-cancelled subscriptions return already_cancelled: true.
An empty JSON object uses the default force: false.
GET /api/v1/service-plan-subscriptions
GET /api/v1/service-plan-subscriptionsRequired 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. |
service_plan_id | string | No | Filter by service plan ID. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
GET /api/v1/service-plan-subscriptions/:id
GET /api/v1/service-plan-subscriptions/: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-plan-subscriptions/:id
PUT /api/v1/service-plan-subscriptions/:idRequired scopes: service_plans:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
contact_id | integer | No | |
property_id | integer or null | No | |
account_manager_id | string or null | No |
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.
POST /api/v1/service-plan-subscriptions/:id/cancel
POST /api/v1/service-plan-subscriptions/:id/cancelRequired scopes: service_plans:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
force | boolean | No | Default: false. |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.