API Key1

Approval Workflow Models5

Approval Workflows3

Bank accounts5

Bank Transactions5

Bill Payments3

Bills10

Books1

Books periods5

Cash Matching3

Charges5

Chart of Accounts7

Close Checklist4

Contract Documents3

Contract Items3

Contracts15

Credit Memos8

Customer Families8

Customer Payments2

Customers9

Draft Contract Documents3

Draft Contracts5

External Reference Types1

Feedback1

Fields6

Health1

Invoice Documents3

Invoice payments5

Invoices12

Journal Entries5

Journal Entry Documents2

Members1

Metadata1

Organizations1

Products6

Reimbursement Payments3

Reimbursements5

Reports7

Roles2

Subsidiaries2

Tax rates1

Vendor Credit Applications1

Vendor Credits5

Vendors5

Webhooks

Webhooks23

Contracts

Creates a contract

Changed on Nov 3, 2026

A matching contract approval rule returns HTTP 202 with contract_id and approval_request_id instead of the contract. This is a proposal, not a created contract: nothing is created until the request is approved, and the contract then keeps contract_id. To check on it, retrieve-a-draft-contract with contract_id shows a FULL contract waiting as a draft and its approval.status (WAITING, REJECTED, CANCELLED or WITHDRAWN); once approved, retrieve-a-contract returns it. Pass idempotency_key on the first call and keep it across retries: a retry with the same key answers with what the first call made (the contract, or the request it waits on) instead of making a second contract. The key is optional; each call without one makes a new contract. A key whose request was rejected or cancelled is closed; send the contract again with a new key.

Rillet supports two contract scope types: FULL and REVENUE_RECOGNITION_ONLY. The selected scope determines how the invoices are created and what information the user needs to provide.

The FULL scope is used when contract invoices are generated and sent directly from Rillet. In this case, Rillet automatically assigns the invoice numbers.

The REVENUE_RECOGNITION_ONLY scope is intended for situations where contracts and invoices are issued from another system and only need to be recorded in Rillet for accounting purposes. In this workflow, users must provide the invoice numbers manually. Other fields can be populated based on the data imported from the external system.

For example, if your organization issues invoices through an external billing platform but tracks financials in Rillet, you should select REVENUE_RECOGNITION_ONLY. If Rillet handles the entire invoicing and sending process, choose the FULL scope.

post/contracts

Request

Base URL
https://api.rillet.com
Auth
HTTP bearer
TypeScript
https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/contracts/post.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

idempotency_keystring uuid

Stable key for retries of the same contract. A retry with the same key returns what the first call made instead of a second contract. Use a new key for a different contract.

Request body

Example request

{
  "name": "New API Contract",
  "items": [
    {
      "price": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "interval_months": 1
      },
      "quantity": 1,
      "progress_plan": {
        "milestones": [
          {
            "key": "design-approved",
            "name": "Design approved",
            "sequence": 1,
            "percentage": "30",
            "amount": {
              "amount": "1.01",
              "currency": "USD"
            }
          }
        ]
      },
      "discount": {
        "amount_off": {
          "amount": "1.01",
          "currency": "USD"
        }
      },
      "tax_rate": {
        "percentage": "0",
        "tax_amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "country": "US"
      },
      "external_reference": {
        "type": "xyzSystemId",
        "id": "234",
        "url": "https://xyzsystempage.com/ids/234"
      },
      "usage_minimum_commitment": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "revenue_account": "11112"
      },
      "declared_ssp": {
        "amount": "1.01",
        "currency": "USD"
      }
    }
  ],
  "invoicing": {
    "day": 1
  },
  "usage_configuration": {
    "contract_level_minimum_commitment": {
      "amount": {
        "amount": "1.01",
        "currency": "USD"
      },
      "revenue_account": "11112"
    }
  },
  "external_references": [
    {
      "type": "xyzSystemId",
      "id": "234",
      "url": "https://xyzsystempage.com/ids/234"
    }
  ],
  "exchange_rate": {
    "base": "USD",
    "target": "USD"
  },
  "invoice_schedule": {
    "invoices": [
      {
        "currency": "USD",
        "total": {
          "amount": "1.01",
          "currency": "USD"
        },
        "items": [
          {
            "unit_amount": {
              "amount": "1.01",
              "currency": "USD"
            },
            "total_amount": {
              "amount": "1.01",
              "currency": "USD"
            }
          }
        ]
      }
    ]
  }
}

Response

idstring uuid required

customer_idstring uuid required

subsidiary_idstring uuid required

namestring required

status'ACTIVE' | 'IN_EFFECT' | 'CANCELLED' | 'ENDED' | 'AMENDED' required

start_datestring date required

end_datestring date

close_datestring date required

metadataobject

Contract metadata values keyed by metadata definition key.

purchase_order_numberstring

Purchase order number set on the contract. It is copied onto every invoice the contract generates. Null when none was set.

shipping_customer_idstring uuid nullable

The customer the contract ships to. Equal to customer_id when shipping to the billing customer. Null when no ship-to customer is set.

Example response

{
  "name": "New API Contract",
  "items": [
    {
      "price": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "interval_months": 1
      },
      "quantity": "1",
      "total_value": {
        "amount": "1.01",
        "currency": "USD"
      },
      "progress_plan": {
        "milestones": [
          {
            "allocated_amount": {
              "amount": "1.01",
              "currency": "USD"
            },
            "amount": {
              "amount": "1.01",
              "currency": "USD"
            },
            "external_references": [
              {
                "type": "xyzSystemId",
                "id": "234",
                "url": "https://xyzsystempage.com/ids/234"
              }
            ]
          }
        ]
      },
      "discount": {
        "amount_off": {
          "amount": "1.01",
          "currency": "USD"
        }
      },
      "tax_rate": {
        "percentage": "0",
        "tax_amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "country": "US"
      },
      "external_references": [
        {
          "type": "xyzSystemId",
          "id": "234",
          "url": "https://xyzsystempage.com/ids/234"
        }
      ],
      "usage_minimum_commitment": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "revenue_account": "11112"
      },
      "bundle": {
        "components": [
          {
            "quantity": "1",
            "allocated_amount": {
              "amount": "1.01",
              "currency": "USD"
            }
          }
        ]
      },
      "declared_ssp": {
        "amount": "1.01",
        "currency": "USD"
      }
    }
  ],
  "invoicing": {
    "day": 1
  },
  "usage_configuration": {
    "contract_level_minimum_commitment": {
      "amount": {
        "amount": "1.01",
        "currency": "USD"
      },
      "revenue_account": "11112"
    }
  },
  "total_value": {
    "amount": "1.01",
    "currency": "USD"
  },
  "external_references": [
    {
      "type": "xyzSystemId",
      "id": "234",
      "url": "https://xyzsystempage.com/ids/234"
    }
  ],
  "exchange_rate": {
    "base": "USD",
    "target": "USD"
  },
  "purchase_order_number": "PO-12345",
  "billing_address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Nashville",
    "state": "TN",
    "zip_code": "37201",
    "country": "US"
  },
  "shipping_address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Nashville",
    "state": "TN",
    "zip_code": "37201",
    "country": "US"
  },
  "invoices": [
    {
      "invoice_number": "INV01",
      "total": {
        "amount": "1.01",
        "currency": "USD"
      },
      "taxed_amount": {
        "amount": "1.01",
        "currency": "USD"
      },
      "items": [
        {
          "description": "Description",
          "revenue": {
            "account_code": "11112"
          },
          "total_amount": {
            "amount": "1.01",
            "currency": "USD"
          },
          "total_discount": {
            "amount": "1.01",
            "currency": "USD"
          },
          "taxed_amount": {
            "amount": "1.01",
            "currency": "USD"
          },
          "gross_rate": {
            "amount": "1.01",
            "currency": "USD"
          },
          "quantity": "1.0000",
          "external_references": [
            {
              "type": "xyzSystemId",
              "id": "234",
              "url": "https://xyzsystempage.com/ids/234"
            }
          ]
        }
      ],
      "external_references": [
        {
          "type": "xyzSystemId",
          "id": "234",
          "url": "https://xyzsystempage.com/ids/234"
        }
      ]
    }
  ]
}

Changes

Nov 3, 2026c393d0102005 Revision changes
- breaking
  added to the ////// request property allOf list
- breaking
  removed the enum value DAILY of the request property //////
- breaking
  removed the enum value EVEN_PERIOD of the request property //////
- breaking
  the ////// request property type changed from string to no type
- breaking
  the /////// request property type changed from number to string, and format from no format to number
- breaking
  the ///////// request property type changed from number to string, and format from no format to number
- breaking
  the response property ////// became optional for the status
- breaking
  the ////// response's property type changed from number to string, and format from no format to number for status
- breaking
  the ////// response's property type changed from string to no type for status
- breaking
  the /////////// response's property type changed from number to string, and format from no format to number for status
- breaking
  the ///// response's property type changed from number to string, and format from no format to number for status
- warning
  added the new PROGRESS enum value to the ////// response property for the response status
- info
  added the new optional query request parameter idempotency_key
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property //////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property ////
- info
  added the new optional request property //////
- info
  the request property ////// became optional
- info
  added the new PROGRESS enum value to the request property //////
- info
  added the non-success response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property / to the response with the status
- info
  added to the ////// response property allOf list for the response status
- info
  added subschema #1 subschema #2 to the ///// response property allOf list for the response status
- info
  removed the DAILY enum value from the ////// response property for the response status
- info
  removed the EVEN_PERIOD enum value from the ////// response property for the response status
- info
  added the required property //// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the success response with the status

Operation history