The Contract object

{
  "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"
}

{
  "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"
}

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.

{
  "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"
}

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.

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

Retrieve a contract

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

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 with requireSignature: true.

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.

Scopes

All three endpoints need the billing:read scope.

Introduction

Endpoints

Embeds & real-time

Attributes

List contracts

Retrieve a contract

List contract templates

Renewals

Scopes

​Attributes

​List contracts

​Retrieve a contract

​List contract templates

​Renewals

​Scopes

Attributes

List contracts

Retrieve a contract

List contract templates

Renewals

Scopes