developers
Base URL: https://couplrfsm.com/api/v1. Conventions shared by every endpoint (examples, ids, dates, money) are on the API reference page. Errors, pagination and idempotency are in Errors, limits and retries.
List maintenance plans#
GET /api/v1/maintenance-plans · requires the plans:read ability
The plans the company sells, in name order. A plan counts as changed for updated_since when one of its prices changes.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page |
integer | No | Default: 1. |
per_page |
integer | No | Values above 100 are served as 100. Default: 25. |
updated_since |
string (date-time) | No | Only records changed at or after this time. ISO 8601, for example 2026-11-14T15:00:00Z. |
Example request
curl "https://couplrfsm.com/api/v1/maintenance-plans" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response (200)
{
"data": [
{
"id": 12,
"name": "Comfort Club",
"description": "Two tune-ups a year and priority scheduling.",
"visits_per_year": 2,
"prices": [
{
"billing_frequency": "month",
"price": "19.00"
},
{
"billing_frequency": "year",
"price": "199.00"
}
],
"created_at": "2026-03-02T16:00:00+00:00",
"updated_at": "2026-03-02T16:00:00+00:00"
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 1,
"last_page": 1
}
}
Errors
| Status | When |
|---|---|
401 |
No key (api_key_missing), the key is unknown or revoked (api_key_invalid), the key had an end date that has passed (api_key_expired), or the key belongs to a private trial sandbox whose access window has ended (sandbox_expired). |
403 |
The key lacks the ability this endpoint needs (ability_missing), no admin user is left to act for the key (no_acting_admin), or the company's account is not yet verified. |
422 |
A parameter or field is invalid (validation_failed). errors maps each field to its messages. |
429 |
Too many requests (rate_limited). Wait Retry-After seconds. |
Get a maintenance plan#
GET /api/v1/maintenance-plans/{id} · requires the plans:read ability
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes |
Example request
curl "https://couplrfsm.com/api/v1/maintenance-plans/1842" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response (200)
{
"data": {
"id": 12,
"name": "Comfort Club",
"description": "Two tune-ups a year and priority scheduling.",
"visits_per_year": 2,
"prices": [
{
"billing_frequency": "month",
"price": "19.00"
},
{
"billing_frequency": "year",
"price": "199.00"
}
],
"created_at": "2026-03-02T16:00:00+00:00",
"updated_at": "2026-03-02T16:00:00+00:00"
}
}
Errors
| Status | When |
|---|---|
401 |
No key (api_key_missing), the key is unknown or revoked (api_key_invalid), the key had an end date that has passed (api_key_expired), or the key belongs to a private trial sandbox whose access window has ended (sandbox_expired). |
403 |
The key lacks the ability this endpoint needs (ability_missing), no admin user is left to act for the key (no_acting_admin), or the company's account is not yet verified. |
404 |
No such record in this company (not_found). |
429 |
Too many requests (rate_limited). Wait Retry-After seconds. |
List plan enrollments#
GET /api/v1/maintenance-plan-enrollments · requires the plans:read ability
Each customer's enrollment in a plan, newest first.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page |
integer | No | Default: 1. |
per_page |
integer | No | Values above 100 are served as 100. Default: 25. |
updated_since |
string (date-time) | No | Only records changed at or after this time. ISO 8601, for example 2026-11-14T15:00:00Z. |
customer_id |
integer | No | |
plan_id |
integer | No | |
status |
string | No | Exact status match, e.g. active. |
Example request
curl "https://couplrfsm.com/api/v1/maintenance-plan-enrollments" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response (200)
{
"data": [
{
"id": 340,
"plan_id": 12,
"plan_name": "Comfort Club",
"customer_id": 1842,
"customer_name": "Dana Whitfield",
"address_id": 2210,
"status": "active",
"start_date": "2026-03-15",
"number_of_systems": 1,
"billing_frequency": "month",
"recurring_amount": "19.00",
"next_billing_date": "2026-12-15",
"checkout_url": null,
"created_at": "2026-03-15T17:20:05+00:00",
"updated_at": "2026-11-15T09:00:00+00:00"
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 1,
"last_page": 1
}
}
Errors
| Status | When |
|---|---|
401 |
No key (api_key_missing), the key is unknown or revoked (api_key_invalid), the key had an end date that has passed (api_key_expired), or the key belongs to a private trial sandbox whose access window has ended (sandbox_expired). |
403 |
The key lacks the ability this endpoint needs (ability_missing), no admin user is left to act for the key (no_acting_admin), or the company's account is not yet verified. |
422 |
A parameter or field is invalid (validation_failed). errors maps each field to its messages. |
429 |
Too many requests (rate_limited). Wait Retry-After seconds. |
Enroll a customer in a plan#
POST /api/v1/maintenance-plan-enrollments · requires the plans:write ability · accepts Idempotency-Key
Starts an enrollment. It is created with status pending payment
and a checkout_url: Couplr's checkout page for this customer and
plan. Nothing is charged by this call. Billing starts when the
customer completes the checkout page, and the enrollment then
becomes active.
Couplr also books the plan's first visit on the schedule and, if the customer uses email, sends them the plan email with the checkout link, as it does when someone enrolls a customer in the apps.
billing_frequency must be one of the plan's current prices. The
price is the plan's own; it cannot be set here, and neither can a
discount.
A repeat of the same enrollment within a few minutes returns the
first one with 200 instead of creating a second.
Refused with 422 when the account has no checkout page for the
customer to complete (on plan_id); enroll the customer in Couplr
instead. If the checkout page cannot be created at that moment, the
answer is also a 422: the enrollment is kept as pending payment
in Couplr for the office to send, and is never made active. An enrollment cannot be changed or cancelled through the API.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key |
string | No | Makes a retry of this request safe. See "Retries and idempotency". |
Request body (application/json)
Fields not listed are ignored.
| Field | Type | Required | Description |
|---|---|---|---|
customer_id |
integer | Yes | |
plan_id |
integer | Yes | |
billing_frequency |
string | Yes | One of the plan's prices, e.g. month or year. |
address_id |
integer or null | No | The address the plan covers. Omit to use the customer's main address. |
start_date |
string (date) or null | No | Defaults to today. |
number_of_systems |
integer | No | Default: 1. |
notes |
string or null | No |
Example request
curl -X POST "https://couplrfsm.com/api/v1/maintenance-plan-enrollments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_KEY" \
-d '{"customer_id":1842,"plan_id":12,"billing_frequency":"month"}'
Example response (200)
{
"data": {
"id": 340,
"plan_id": 12,
"plan_name": "Comfort Club",
"customer_id": 1842,
"customer_name": "Dana Whitfield",
"address_id": 2210,
"status": "active",
"start_date": "2026-03-15",
"number_of_systems": 1,
"billing_frequency": "month",
"recurring_amount": "19.00",
"next_billing_date": "2026-12-15",
"checkout_url": null,
"created_at": "2026-03-15T17:20:05+00:00",
"updated_at": "2026-11-15T09:00:00+00:00"
}
}
Example response (201)
{
"data": {
"id": 340,
"plan_id": 12,
"plan_name": "Comfort Club",
"customer_id": 1842,
"customer_name": "Dana Whitfield",
"address_id": 2210,
"status": "active",
"start_date": "2026-03-15",
"number_of_systems": 1,
"billing_frequency": "month",
"recurring_amount": "19.00",
"next_billing_date": "2026-12-15",
"checkout_url": null,
"created_at": "2026-03-15T17:20:05+00:00",
"updated_at": "2026-11-15T09:00:00+00:00"
}
}
Errors
| Status | When |
|---|---|
401 |
No key (api_key_missing), the key is unknown or revoked (api_key_invalid), the key had an end date that has passed (api_key_expired), or the key belongs to a private trial sandbox whose access window has ended (sandbox_expired). |
403 |
The key lacks the ability this endpoint needs (ability_missing), no admin user is left to act for the key (no_acting_admin), or the company's account is not yet verified. |
422 |
A parameter or field is invalid (validation_failed). errors maps each field to its messages. |
429 |
Too many requests (rate_limited). Wait Retry-After seconds. |
Get a plan enrollment#
GET /api/v1/maintenance-plan-enrollments/{id} · requires the plans:read ability
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes |
Example request
curl "https://couplrfsm.com/api/v1/maintenance-plan-enrollments/1842" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response (200)
{
"data": {
"id": 340,
"plan_id": 12,
"plan_name": "Comfort Club",
"customer_id": 1842,
"customer_name": "Dana Whitfield",
"address_id": 2210,
"status": "active",
"start_date": "2026-03-15",
"number_of_systems": 1,
"billing_frequency": "month",
"recurring_amount": "19.00",
"next_billing_date": "2026-12-15",
"checkout_url": null,
"created_at": "2026-03-15T17:20:05+00:00",
"updated_at": "2026-11-15T09:00:00+00:00"
}
}
Errors
| Status | When |
|---|---|
401 |
No key (api_key_missing), the key is unknown or revoked (api_key_invalid), the key had an end date that has passed (api_key_expired), or the key belongs to a private trial sandbox whose access window has ended (sandbox_expired). |
403 |
The key lacks the ability this endpoint needs (ability_missing), no admin user is left to act for the key (no_acting_admin), or the company's account is not yet verified. |
404 |
No such record in this company (not_found). |
429 |
Too many requests (rate_limited). Wait Retry-After seconds. |