--- title: "Creates a draft contract" method: POST path: "/draft-contracts" tags: ["Draft Contracts"] --- # Creates a draft contract `POST /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. ## Request body - CreateDraftContractRequest - `external_references` ExternalReference[] — 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. - `type` string, required - `id` string, required - `url` string, uri - `subsidiary_id` string, uuid, required - `customer_id` string, uuid, required — Must reference a customer that already exists in Rillet. Use `POST /customers` first if needed. - `name` string, required - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `close_date` string, date, required - `start_date` string, date - `end_date` string, date - `scope` 'FULL' | 'REVENUE_RECOGNITION_ONLY', required — The "FULL" scope includes revenue recognition and invoicing handled in Rillet. With the "REVENUE_RECOGNITION_ONLY" scope, invoicing is handled outside Rillet. - `items` DraftContractItemRequest[], required — Contract line items. At least one item is required. - `product_id` string, uuid, required - `price` union, required - FixedRecurringPrice - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `interval_months` integer, required - `type` string, required - OneTimePrice - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `type` string, required - UsagePrice - `interval_months` integer, required - `type` string, required - `billing_scheme` union, required - PerUnitBilling - `type` string, required - `amount` MonetaryAmount, required - … - `units` integer, required - TieredBilling — All tiers except for the highest have to define a value for upTo. There cannot be more than one tier with the same upTo value. - `type` string, required - `mode` 'GRADUATED' | 'METERED', required — In metered tiering, the maximum quantity within a period determines the price. In graduated tiering, pricing changes as the quantity grows – the price from each tier up to the reported quantity is accumulated. - `tiers` Tier[], required - … - `quantity` number, required - `discount` union - AmountDiscount - `amount_off` RoundedMonetaryAmount, required — A monetary amount that must be rounded to the currency's default decimal places (e.g., 2 decimal places for USD). - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. Must be rounded to the currency's default decimal places (e.g. '1.01' in USD represents 1 dollar and 1 cent). - `currency` string, required — Currency code following ISO-4217 - `type` string - PercentageDiscount - `percentage_off` number, double, required - `type` string - `start_date` string, date - `end_date` string, date ## Response `200` OK - DraftContract - `id` string, uuid, required - `external_references` ExternalReference[], required - `type` string, required - `id` string, required - `url` string, uri - `subsidiary_id` string, uuid, required - `customer_id` string, uuid, required - `name` string, required - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `close_date` string, date, required - `start_date` string, date - `end_date` string, date - `scope` 'FULL' | 'REVENUE_RECOGNITION_ONLY' — The "FULL" scope includes revenue recognition and invoicing handled in Rillet. With the "REVENUE_RECOGNITION_ONLY" scope, invoicing is handled outside Rillet. - `items` DraftContractItem[], required - `id` string, uuid, required - `product_id` string, uuid, required - `price` union, required - FixedRecurringPrice - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `interval_months` integer, required - `type` string, required - OneTimePrice - `amount` MonetaryAmount, required - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. (e.g. '1.01' in $ currency represents 1$ and 1 cent.) - `currency` string, required — Currency code following ISO-4217 - `type` string, required - UsagePrice - `interval_months` integer, required - `type` string, required - `billing_scheme` union, required - PerUnitBilling - `type` string, required - `amount` MonetaryAmount, required - … - `units` integer, required - TieredBilling — All tiers except for the highest have to define a value for upTo. There cannot be more than one tier with the same upTo value. - `type` string, required - `mode` 'GRADUATED' | 'METERED', required — In metered tiering, the maximum quantity within a period determines the price. In graduated tiering, pricing changes as the quantity grows – the price from each tier up to the reported quantity is accumulated. - `tiers` Tier[], required - … - `quantity` number, required - `discount` union - AmountDiscount - `amount_off` RoundedMonetaryAmount, required — A monetary amount that must be rounded to the currency's default decimal places (e.g., 2 decimal places for USD). - `amount` string, required — Monetary amount in decimal format, using a period (.) as the decimal separator. Must be rounded to the currency's default decimal places (e.g. '1.01' in USD represents 1 dollar and 1 cent). - `currency` string, required — Currency code following ISO-4217 - `type` string - PercentageDiscount - `percentage_off` number, double, required - `type` string - `start_date` string, date - `end_date` string, date ## Other responses - `default` — Error --- [API](https://skmtc.net/rillet/apis/rillet-accounting-api.md) · [All operations](https://skmtc.net/rillet/apis/rillet-accounting-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rillet/rillet-accounting-api/versions/a2ab794dd5f2/schema)