Creates a draft contract

post

https://api.rillet.com/draft-contracts

Stages a contract in the "draft" holding state instead of creating it directly as an active contract.
Draft contracts appear in the Rillet UI under "Draft" for a human to approve or reject.

Deduplication

To prevent duplicate draft contracts on retry, supply at least one external_references entry with a
stable (type, id) pair. When you POST again with any matching (type, id) pair, the prior draft record
is replaced with the new payload.

Draft contracts created without any external_references are not deduplicated — every POST creates a new
record.

External reference types

Each reference's type must match a slug already defined under Rillet Settings → External References for
the organization; unknown slugs return a 400. References attached at create time are preserved when the
draft contract is promoted to an active contract.

Promotion

Promotion to an active contract happens through the Rillet UI. The public API does not currently expose a
programmatic promotion endpoint.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

external_references

array of objects, unique

Cross-system identifiers for this draft contract. Each reference's type slug must already exist in
the org's external reference types (configurable in Rillet Settings).

Required for deduplication. Re-posting with any matching (type, id) pair replaces the prior draft
record. Draft contracts created without external_references are not deduplicated.

external_references

subsidiary_id

uuid

required

customer_id

uuid

required

Must reference a customer that already exists in Rillet. Use POST /customers first if needed.

name

string

required

amount

object

required

close_date

date

required

start_date

date

end_date

date

scope

string

enum

required

The "FULL" scope includes revenue recognition and invoicing handled in Rillet. With the "REVENUE_RECOGNITION_ONLY" scope, invoicing is handled outside Rillet.

Allowed:

items

array of objects

required

length ≥ 1

Contract line items. At least one item is required.

items*

purchase_order_number

string

length ≤ 50

Optional purchase order number, carried onto the contract created from this draft and from there onto every invoice it generates.

shipping_customer_id

uuid | null

The customer to ship to. Omit, send null, or send customer_id to ship to the billing customer. On update, omit to keep the current ship-to customer, or send null to remove it and its shipping address; null with a shipping_address_id ships to the billing customer.

billing_address_id

uuid | null

ID of one of the billing customer's billing_addresses. If omitted, the first address in the customer's billing_addresses is used, or none when the customer has no billing address. Send null for no billing address. On update, omit to keep the current billing address, or send null to remove it. Rejected when the address does not belong to the billing customer or is not a billing address.

shipping_address_id

uuid | null

ID of one of the ship-to customer's shipping_addresses. If omitted, the first address in the ship-to customer's shipping_addresses is used, or none when it has no shipping address. Send null for no shipping address. On update, omit to keep the current shipping address, or send null to remove it; a new shipping_customer_id sent without this field takes that customer's first shipping address. Rejected when the address does not belong to the ship-to customer or is not a shipping address.

email_selection

object

Who receives the invoices of the contract created from this draft. If omitted, none is specified and the reviewer starts from all of the billing customer's emails. On update, omit to keep the current selection, or send ALL_CUSTOMER_EMAILS to follow the customer's emails. A draft keeps one entry per email, the first one sent. With SELECTED_EMAILS and no MAIN_SENDER recipient left, including an empty recipients list, no selection is stored, the same as the review page. A stored recipient that is not one of the billing customer's emails is rejected.

Responses

Language

Credentials

Bearer

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK

defaultError