---
title: "Preview the invoice schedule for a contract"
method: POST
path: "/contracts/preview-invoice-schedule"
tags: ["Contracts"]
---

# Preview the invoice schedule for a contract

`POST /contracts/preview-invoice-schedule`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/contracts/preview-invoice-schedule`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/contracts/preview-invoice-schedule/post.ts> (a function with typed inputs; its response is checked against the schema)

Computes and returns the invoice schedule the given contract would produce, without creating the contract or persisting anything.

## Request body

- union
  - object
    - `name` string, required
    - `close_date` string, date, required
    - `start_date` string, date, required
    - `end_date` string, date
    - `items` ContractItemRequest[], required
      - `id` string: A request-scoped identifier for this contract item, echoed back as contract_item_id on each invoice_schedule line. Required on the preview-invoice-schedule request and, when invoice_schedule is supplied, on create; otherwise optional and ignored. When present, ids must be unique within the request.
      - `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
              - …
            - 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.
              - …
      - `quantity` number, required: Must be 1 for USAGE prices.
      - `revenue_pattern` 'DAILY' | 'EVEN_PERIOD' | 'PROGRESS': DAILY divides revenue equally per day. EVEN_PERIOD divides revenue equally per calendar month. PROGRESS uses a progress plan; the supported measure MILESTONES recognizes allocated revenue on milestone completion and requires a one-time price. FULL contract creation supports an explicit progress plan or snapshots the referenced product's template. Existing non-progress behavior is unchanged.
      - `progress_plan` ProgressPlanRequest: A complete contract-specific milestone plan. PERCENTAGE milestones require percentage and reject amount; AMOUNT milestones require amount and reject percentage. Definitions are snapshotted on the contract line.
        - `measure` 'MILESTONES', required: The progress measure. Only MILESTONES is currently supported.
        - `value_mode` 'PERCENTAGE' | 'AMOUNT', required: Values are non-negative plain decimal strings with no exponent notation. PERCENTAGE supports at most 4 decimal places; AMOUNT supports at most 10 decimal places. Excess decimal places, including trailing zeros, are rejected rather than rounded. PERCENTAGE values are whole percentages ("30" means 30%), range from 0 to 100, and must total exactly 100. AMOUNT values on product templates are proportional weights in the product's currency and must total more than zero; they are not fixed contract obligations.
        - `milestones` ContractMilestoneRequest[], required
          - `key` string, required: Stable integration identifier, unique within the plan ignoring case. UUID-shaped keys are rejected.
          - `name` string, required: Display name, unique within the plan ignoring case and repeated whitespace.
          - `sequence` integer, required: Ordering within the plan. Each milestone must have a distinct positive JSON integer sequence; fractional numbers and strings are rejected.
          - `percentage` string: Required only in PERCENTAGE mode. A non-negative plain decimal string in 0-100 units; all milestones must total exactly 100. "30" means 30 percent. At most 4 decimal places are allowed, including trailing zeros; excess decimal places are rejected rather than rounded.
          - `amount` RoundedMonetaryAmount: 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
          - `expected_date` string, date, nullable: Optional forecast date within the contract line term. It does not trigger recognition or invoicing.
      - `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
      - `tax_rate` TaxRateWithOptionalAmount
        - `percentage` string, number, required
        - `tax_amount` RoundedMonetaryAmount: 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
        - `country` string, required: Two-letter country code (ISO 3166-1 alpha-2).
        - `type` 'VAT' | 'SALES_TAX', required
        - `description` string, required
      - `start_date` string, date: Defaults to the contract start date.
      - `end_date` string, date: Defaults to the contract end date.
      - `external_reference` ExternalReference: For requests, only pre-defined custom IDs are accepted. In responses, an object imported through an integration (e.g. Stripe) would return the provider's object ID.
        - `type` string, required
        - `id` string, required
        - `url` string, uri
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
      - `usage_minimum_commitment` UsageCommitment
        - `amount` 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
        - `revenue_account` string, required: The account code found in the Chart of Accounts
      - `description` string: Overrides the product description on invoice lines generated for this item. Use it when the same product needs different wording per contract. When omitted or blank, the product's own description is used.
      - `declared_ssp` MonetaryAmount
        - `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
    - `invoicing` union
      - MonthlyInvoicing
        - `payment_terms` integer, required
        - `interval` string, required
        - `day` integer, required
      - MonthlyProratedInvoicing: Monthly prorated invoicing is only available for contracts with usage products and a minimum usage commitment.
        - `payment_terms` integer, required
        - `interval` string, required
        - `day` integer, required
      - QuarterlyInvoicing
        - `payment_terms` integer, required
        - `interval` string, required
        - `month_day` string, required: A string in --MM-dd format. Invoices will be created starting on that date and every 3 months.
      - SemiAnnualInvoicing
        - `payment_terms` integer, required
        - `interval` string, required
        - `month_day` string, required: A string in --MM-dd format. Invoices will be created starting on that date and every 6 months.
      - YearlyInvoicing
        - `payment_terms` integer, required
        - `interval` string, required
        - `month_day` string, required: A string in --MM-dd format
    - `usage_configuration` UsageConfiguration
      - `usage_invoicing` UsageInvoicing, required
        - `frequency` 'MONTHLY' | 'QUARTERLY' | 'SEMI_ANNUAL' | 'YEARLY', required
        - `payment_terms` integer, required
        - `invoice_date` 'FIRST_DAY_OF_NEXT_CYCLE' | 'LAST_DAY_OF_CURRENT_CYCLE', required: When the usage invoice is created in relation to the usage cycle.
        - `cycle` 'CALENDAR' | 'SUBSCRIPTION_ANNIVERSARY', required: When does the invoicing pricing cycle reset and results in an invoice. Calendar option is only allowed when usage invoice frequency is Monthly, and contract does not start on the 1st of the Month.
      - `minimum_commitment_invoicing` MinimumCommitmentInvoicing
        - `frequency` 'MONTHLY' | 'MONTHLY_PRORATED' | 'QUARTERLY' | 'SEMI_ANNUAL' | 'YEARLY', required: MONTHLY_PRORATED is only available for CALENDAR usage invoice cycle. It need to be the same as contract level invoicing frequency.
        - `payment_terms` integer, required
      - `minimum_commitment_cycle` 'MONTHLY' | 'CONTRACT': Determines how often does the minimum commitment reset.
      - `contract_level_minimum_commitment` UsageCommitment
        - `amount` 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
        - `revenue_account` string, required: The account code found in the Chart of Accounts
    - `external_references` ExternalReference[]
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `customer_id` string, uuid, required
    - `subsidiary_id` string, uuid
    - `shipping_customer_id` string, uuid: The customer to ship to. Omit, or send customer_id, to ship to the billing customer.
    - `billing_address_id` string, uuid, nullable: A UUID, or null to explicitly select nothing. Omitting the field is not the same as sending null.
    - `shipping_address_id` string, uuid, nullable: A UUID, or null to explicitly select nothing. Omitting the field is not the same as sending null.
    - `email_selection` EmailSelection
      - `mode` 'ALL_CUSTOMER_EMAILS' | 'SELECTED_EMAILS', required: ALL_CUSTOMER_EMAILS: sent to every email on the billing customer at the time of sending, including emails added later, each as its own type. SELECTED_EMAILS: sent only to recipients.
      - `recipients` EmailRecipient[]
        - `customer_email_id` string, uuid, required: ID of one of the billing customer's emails.
        - `recipient_type` 'MAIN_SENDER' | 'CC' | 'BCC', required: How the email receives the invoice: MAIN_SENDER is To, CC and BCC are copies.
    - `exchange_rate` ExchangeRate
      - `base` string, required: Currency code following ISO-4217
      - `target` string, required: Currency code following ISO-4217
      - `rate` string, required
      - `date` string, date, required
    - `purchase_order_number` string: Optional purchase order number. When set, it is copied onto every invoice generated by the contract.
    - `invoice_schedule` ContractInvoiceSchedule: The computed invoice schedule for a contract, returned by the preview endpoint. When resubmitted on create as invoice_schedule it replaces the FIXED billing layout with an arbitrary set of invoices: for each contract item the submitted FIXED line totals must sum to its computed value (redistribution only), and USAGE / USAGE_COMMITMENT lines are computed by the system and must not be submitted. Revenue recognition and TCV are unaffected. See ContractInvoiceScheduleItem for the per-line rules.
      - `invoices` ContractInvoiceScheduleEntry[], required
        - `issue_date` string, date, required: Editable on create. Must fall within the contract period and outside any closed book-close period.
        - `currency` string, required
        - `total` 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
        - `items` ContractInvoiceScheduleItem[], required
          - `contract_item_id` string: The id of the contract item this line bills, echoing the item's request-scoped id. Resubmit it unchanged on create. Read-only.
          - `description` string, required: Editable on create.
          - `quantity` string, required: Editable on create for FIXED lines only, subject to total_amount == unit_amount × quantity. USAGE and USAGE_COMMITMENT lines must equal the computed value; changes to those lines are rejected. In all cases the sum of a contract item's line totals must equal its computed contract value (redistribution only) — the contract's total billed, revenue, and TCV are unaffected.
          - `price_type` 'FIXED' | 'USAGE' | 'USAGE_COMMITMENT', required
          - `unit_amount` 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
          - `total_amount` 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
          - `billing_period` BillingPeriod, required: The service/coverage window for this invoice line. Unbounded contracts surface sentinel dates 1900-01-01 (start) and 2300-12-31 (end). Editable on create; the create is rejected if end is before start.
            - `start` string, date, required
            - `end` string, date, required
    - `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.
  - object
    - `name` string, required
    - `close_date` string, date: Defaults to the start date if not provided.
    - `start_date` string, date, required
    - `end_date` string, date
    - `items` RevenueRecognitionOnlyContractItemRequest[], required
      - `product_id` string, uuid, required
      - `price` 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
      - `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
      - `revenue_pattern` 'DAILY' | 'EVEN_PERIOD' | 'PROGRESS', required: DAILY divides revenue equally per day. EVEN_PERIOD divides revenue equally per calendar month. PROGRESS uses a progress plan; the supported measure MILESTONES recognizes allocated revenue on milestone completion and requires a one-time price. FULL contract creation supports an explicit progress plan or snapshots the referenced product's template. Existing non-progress behavior is unchanged.
      - `start_date` string, date: Defaults to the contract start date.
      - `end_date` string, date: Defaults to the contract end date.
      - `external_reference` ExternalReference, required: For requests, only pre-defined custom IDs are accepted. In responses, an object imported through an integration (e.g. Stripe) would return the provider's object ID.
        - `type` string, required
        - `id` string, required
        - `url` string, uri
      - `declared_ssp` MonetaryAmount
        - `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
    - `invoice_schedule` InvoiceSchedule, required
      - `invoices` InvoiceScheduleInvoice[]
        - `due_date` string, date: Defaults to invoice_date, if not provided
        - `invoice_date` string, date, required
        - `invoice_number` string, required
        - `tax_amount` RoundedMonetaryAmount: 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
        - `items` InvoiceScheduleInvoiceItem[], required
          - `description` string, required
          - `contract_item_reference` string, required: Refers to the ID of the contract item's external_reference.
          - `quantity` string, number, required
          - `total_amount` 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
          - `tax_amount` RoundedMonetaryAmount: 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
          - `discount_amount` RoundedMonetaryAmount: 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
          - `external_references` ExternalReference[], required
            - `type` string, required
            - `id` string, required
            - `url` string, uri
        - `external_references` ExternalReference[], required
          - `type` string, required
          - `id` string, required
          - `url` string, uri
    - `external_references` ExternalReference[], required
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `customer_id` string, uuid, required
    - `subsidiary_id` string, uuid
    - `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.

## Response `200`

The computed invoice schedule

- ContractInvoiceSchedule: The computed invoice schedule for a contract, returned by the preview endpoint. When resubmitted on create as invoice_schedule it replaces the FIXED billing layout with an arbitrary set of invoices: for each contract item the submitted FIXED line totals must sum to its computed value (redistribution only), and USAGE / USAGE_COMMITMENT lines are computed by the system and must not be submitted. Revenue recognition and TCV are unaffected. See ContractInvoiceScheduleItem for the per-line rules.
  - `invoices` ContractInvoiceScheduleEntry[], required
    - `issue_date` string, date, required: Editable on create. Must fall within the contract period and outside any closed book-close period.
    - `currency` string, required
    - `total` 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
    - `items` ContractInvoiceScheduleItem[], required
      - `contract_item_id` string: The id of the contract item this line bills, echoing the item's request-scoped id. Resubmit it unchanged on create. Read-only.
      - `description` string, required: Editable on create.
      - `quantity` string, required: Editable on create for FIXED lines only, subject to total_amount == unit_amount × quantity. USAGE and USAGE_COMMITMENT lines must equal the computed value; changes to those lines are rejected. In all cases the sum of a contract item's line totals must equal its computed contract value (redistribution only) — the contract's total billed, revenue, and TCV are unaffected.
      - `price_type` 'FIXED' | 'USAGE' | 'USAGE_COMMITMENT', required
      - `unit_amount` 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
      - `total_amount` 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
      - `billing_period` BillingPeriod, required: The service/coverage window for this invoice line. Unbounded contracts surface sentinel dates 1900-01-01 (start) and 2300-12-31 (end). Editable on create; the create is rejected if end is before start.
        - `start` string, date, required
        - `end` string, date, required

## Other responses

- `default`: Error

## Changes

- **2026-11-03** `c393d0102005`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/contracts/preview-invoice-schedule/post.md)

---

[API](https://skmtc.dev/rillet/apis/rillet-accounting-api.md) - [All operations](https://skmtc.dev/rillet/apis/rillet-accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rillet/apis/rillet-accounting-api/revisions/c393d0102005?raw)