> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Contract object

> Read the agreements your workspace has with its customers: value, term, status and renewal.

A **contract** is the agreement a customer is on. It is written when a quote is accepted, or by a person in Custral. Through the API you can read contracts; creating one is done in the app.

Amounts are in minor units (cents), like every other revenue response.

<ResponseExample>
  ```json The Contract object theme={null}
  {
    "id": "ctr_3Ab9xK2mQ7",
    "number": "C-0007",
    "title": "Master services agreement",
    "status": "renewing",
    "source": "quote",
    "customer": {"recordId": "rec_5Bc0xJ1kP4", "name": "Kestrel Logistics"},
    "quoteNumber": "Q-0041",
    "currency": "usd",
    "recurringAmount": 150000,
    "interval": "year",
    "oneTimeAmount": 0,
    "startDate": "2026-01-01",
    "endDate": "2026-12-31",
    "renews": true,
    "noticeDays": 30,
    "currentTermEnd": "2026-12-31",
    "daysToTermEnd": 21,
    "signedName": "Jane Doe",
    "signedTitle": "CFO",
    "signedAt": "2026-01-01T12:00:00.000Z",
    "createdAt": "2026-01-01T12:00:00.000Z"
  }
  ```
</ResponseExample>

## Attributes

| Attribute | Type | Description |
| - | - | - |
| `id` | string | The contract's id. |
| `number` | string | Its number, such as `C-0007`. |
| `title` | string \| null | Its name, when one was given. |
| `status` | string | `pending`, `upcoming`, `active`, `renewing`, `ending`, `ended` or `cancelled`. |
| `source` | string | `quote` (an accepted quote), `direct` (billing started without a quote) or `recorded` (signed elsewhere) or `checkout` (a plan the customer chose on their billing page). |
| `customer` | object | The customer record: `recordId` and `name`. |
| `quoteNumber` | string \| null | The quote it came from, by number. |
| `recurringAmount` | integer \| null | What it bills each `interval`, in minor units. |
| `interval` | string \| null | `month` or `year`. |
| `oneTimeAmount` | integer | One-time value, in minor units. |
| `startDate` / `endDate` | string | `YYYY-MM-DD`; `endDate` is null for month to month. |
| `renews` | boolean | Whether the term rolls forward at its end. |
| `noticeDays` | integer | Days before the term ends when it counts as renewing or ending. |
| `currentTermEnd` | string \| null | The end of the term in force, rolled forward for a renewing contract. |
| `daysToTermEnd` | integer \| null | Days until `currentTermEnd`. |
| `signedName` / `signedTitle` / `signedAt` | string \| null | Who signed it on the quote page, and when. |

## List contracts

`GET /v1/contracts` lists the workspace's contracts. Filter with `customer` (your app's customer id or a record id) and `status`.

```ts theme={null}
const renewing = await custral.contracts.list({status: "renewing"});
```

## Retrieve a contract

`GET /v1/contracts/{id}` returns one contract.

```ts theme={null}
const contract = await custral.contracts.retrieve("ctr_3Ab9xK2mQ7");
```

## List contract templates

`GET /v1/contract-templates` lists the contracts a quote can ask its customer to sign: each one's `id`, `name`, `kind` (`pdf` for your own document, `text` for one written in Custral) and `isDefault`. Pass an `id` or `name` as `contractTemplate` on [`POST /v1/quotes`](/dev/api-reference/quotes) with `requireSignature: true`.

```ts theme={null}
const templates = await custral.contractTemplates.list();
await custral.quotes.create({
  customer: "acct_1042",
  products: [{product: "Growth seat", quantity: 12}],
  requireSignature: true,
  contractTemplate: "Master services agreement",
});
```

## Renewals

Subscribe to the `contract.renewing` webhook to hear when a contract comes within its notice days of its end. It fires once per term. See [Quote and billing events](/dev/webhooks/events/quotes-and-billing).

## Scopes

All three endpoints need the `billing:read` scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.