# Service contracts

A **service contract** is recurring work a customer signed up for, such as weekly lot sweeping, porter service or a yearly crack fill. In TruTec it lives under **Service contracts**: the contract puts each visit on the crew schedule, bills on its own plan and comes up for renewal before it ends.

You can read contracts, write a new one, change it, and activate or pause it. Sending the agreement to the customer to sign, invoices and renewals stay in the app. A workspace needs TruTec Bid or Build to have service contracts; other workspaces get `403`. Every contract carries the `job_id` of the job that holds its visits, costs and invoices (empty until it is activated, unless you wrote it on a job).

## List contracts

`GET /v1/service-contracts` returns the workspace's contracts, most recently changed first, a page at a time (`limit`, `offset`).

| Filter | What it does |
|---|---|
| `status` | `draft`, `active`, `paused`, `ended` or `cancelled` |
| `client_account_id`, `location_id`, `job_id` | One customer, one site, or the contract that runs on a job |
| `renews_before` | Renewal date (or end date when no renewal date is set) on or before this day, `YYYY-MM-DD` |
| `updated_after` | Changed after this time (ISO 8601), for syncing |
| `q` | Words in the contract name or number |

```bash
curl "https://trutec.ai/api/v1/service-contracts?status=active&renews_before=2027-03-31" \
  -H "X-API-Key: $TRUTEC_API_KEY"
```

Each contract carries its `total` for the year in dollars, `billing_mode` (how it is invoiced), the `job_id` that holds its visits, costs and invoices, and `renews_by_itself`.

## Get one contract

`GET /v1/service-contracts/{contract_id}` adds:

- `services`: each service with how often it runs (`frequency`, `weekdays` where 0 is Monday, `start_time` and `end_time`), its season, the visits contracted and the price (`price_per_visit` or a flat `season_price`)
- `visits`: how many visits are planned, on the schedule, done, skipped, missed or cancelled

## Write a new contract

`POST /v1/service-contracts` saves a **draft**. Nothing goes on the schedule, nothing is billed and nothing is sent to the customer until it is activated. Send the site or customer, the term, and the services:

```bash
curl -X POST "https://trutec.ai/api/v1/service-contracts" \
  -H "X-API-Key: $TRUTEC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "location_id": 15520,
    "starts_on": "2027-04-01",
    "ends_on": "2028-03-31",
    "billing_mode": "monthly",
    "services": [
      {"name": "Night sweep", "frequency": "weekly", "weekdays": [0, 2, 4],
       "start_time": "22:00", "end_time": "02:00", "minutes_per_visit": 90, "price_per_visit": 80},
      {"name": "Crack fill", "frequency": "dates", "dates": ["2027-05-10"], "season_price": 2400}
    ]
  }'
```

| A service's `frequency` | Goes with |
|---|---|
| `weekly`, `biweekly` | `weekdays` (0 is Monday; several are fine) |
| `every_n_days` | `interval_days` |
| `monthly`, `twice_monthly` | `month_days` (one day, or two) |
| `n_per_season` | `visits_contracted`, spread evenly over the season |
| `dates` | `dates`, the days you pick |
| `once` | One visit on the first day |
| `on_call` | Nothing planned ahead (snow, call-outs) |

A service is priced per visit (`price_per_visit`) or with one flat price for the term (`season_price`), not both. `job_id` runs the contract on a job you already have, such as the one that was sold; a job carries one contract at a time. Left out, the job is made when the contract is activated.

The contract is checked the same way as the contract screen. When something is missing you get `422` with the first problem in `error` and all of them in `problems`, in plain words ("Pick the customer."). Writes act as the key's creator, who needs to be an owner or have **See prices and costs**, and **Invoices and payments** to set how it bills.

## Change a contract

`PATCH /v1/service-contracts/{contract_id}` changes only the fields you send. `services` is the exception: it **replaces the whole list**. Read the contract, change what you need in its `services`, and send them all back with their `id`s. A service without an `id` is added. A service you leave out is removed from a draft, or turned off on a running contract so the visits already done stay.

On a running contract, a change to a service's days, how often or crew starts today, or on `changes_start_on`. Earlier visits and finished ones never change; upcoming ones are planned again. How a contract bills (`billing_mode` and the other billing fields) can be changed here only while it is a draft; after that it is the contract's Billing card in the app. `null` clears `ends_on`, `renewal_date`, `agreed_total`, `tax_percent`, the notes, the site and the account manager.

## Activate and pause

| Call | What it does |
|---|---|
| `POST /v1/service-contracts/{contract_id}/activate` | Starts a draft, or resumes a paused contract. Its visits are made from today on, its job is made if it has none, and with crew scheduling on the visits go on the crew schedule (crews are told when the schedule is next published) |
| `POST /v1/service-contracts/{contract_id}/pause` | Takes the upcoming visits off the schedule until it is activated again. Visits already started or done stay |

Neither takes a body, and neither sends the customer anything. A move that is not possible now (pausing a draft, activating a contract with no services) is a `409` that says why.

## Contracts that run more than one year

A customer can sign for 2 or 3 years with a price step each year. TruTec keeps **one contract per year** of the term, each with its own job, invoices and visits. `term.years` is how long the customer signed for, `term.year` is which year this contract is, and `term.price_step_percent` is how much every price goes up each year. `renewed_from_id` points at the contract before it, so you can walk a term from its first year.

## From ChatGPT or Claude

`get_service_contracts` reads: leave `contract_id` out to list, give it for one contract. `create_service_contract` writes a draft, `update_service_contract` changes one, and `activate_service_contract` and `pause_service_contract` start and pause it. The assistant asks before it activates, since that puts a season of visits on the crew schedule.
