## List service plans

**get** `/service-plans`

Returns a paginated list of service plan agreements for the authenticated company.
Results are ordered by creation date (newest first).

Service plans represent recurring service agreements (e.g. quarterly window cleaning, monthly pressure washing).
The `sale_value` is the total calculated contract value across all jobs in the plan.
The `total_received` is the net amount paid (invoices minus refunds) in dollars.

### Query Parameters

- `created_at_range_end: optional string`

  Return plans created on or before this date (ISO 8601)

- `created_at_range_start: optional string`

  Return plans created on or after this date (ISO 8601)

- `frequency: optional "One-Time" or "Annual" or "Semi-Annual" or 7 more`

  Filter by service frequency name.

  - `"One-Time"`

  - `"Annual"`

  - `"Semi-Annual"`

  - `"Tri-Annual"`

  - `"Quarterly"`

  - `"Bi-Monthly"`

  - `"Monthly"`

  - `"Bi-Weekly"`

  - `"Weekly"`

  - `"Custom"`

- `limit: optional number`

  Number of results per page (max 1000)

- `page: optional number`

  Page number (1-based)

- `service_type: optional string`

  Filter by service type (e.g. `Window Cleaning`, `Pressure Washing`)

- `sold_by_user_id: optional string`

  Filter by the ID of the user who sold the plan

- `status: optional "active" or "inactive"`

  Filter by active/inactive status

  - `"active"`

  - `"inactive"`

### Header Parameters

- `"rotor-api-version": "1.1.0"`

  - `"1.1.0"`

### Returns

- `data: optional array of object { id, active, created_at, 10 more }`

  - `id: optional string`

  - `active: optional boolean`

    Whether the service plan is currently active

  - `created_at: optional string`

  - `customer: optional object { id, company_name, first_name, last_name }`

    - `id: optional string`

    - `company_name: optional string`

    - `first_name: optional string`

    - `last_name: optional string`

  - `num_completed_jobs: optional number`

    Number of jobs in this plan that have been completed

  - `num_pending_jobs: optional number`

    Number of jobs in this plan that are pending and haven't been created or scheduled yet

  - `num_scheduled_jobs: optional number`

    Total number of jobs scheduled in this plan, including completed jobs

  - `sale_value: optional number`

    Total calculated contract value across all jobs in the plan (dollars)

  - `service_frequency: optional string`

    Human-readable recurrence frequency

  - `service_type: optional string`

    Type of service (from plan configuration)

  - `sold_by: optional object { email, name, user_id }`

    - `email: optional string`

    - `name: optional string`

    - `user_id: optional string`

  - `start_date: optional string`

  - `total_received: optional number`

    Net amount paid so far (invoices minus refunds, in dollars)

- `pagination: optional object { has_more, limit, page, total }`

  - `has_more: optional boolean`

    Whether more pages are available

  - `limit: optional number`

  - `page: optional number`

  - `total: optional number`

    Total number of matching records

- `status: optional string`

### Example

```http
curl https://api.getrotor.com/open-api/service-plans \
    -H "x-api-key: $ROTOR_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "active": true,
      "created_at": "2019-12-27T18:11:19.117Z",
      "customer": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "company_name": "company_name",
        "first_name": "first_name",
        "last_name": "last_name"
      },
      "num_completed_jobs": 1,
      "num_pending_jobs": 3,
      "num_scheduled_jobs": 1,
      "sale_value": 1200,
      "service_frequency": "Quarterly",
      "service_type": "Window Cleaning",
      "sold_by": {
        "email": "dev@stainless.com",
        "name": "Jane Smith",
        "user_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "start_date": "2026-03-01",
      "total_received": 600
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 50,
    "page": 1,
    "total": 142
  },
  "status": "success"
}
```