RIrillet
Draft Contracts

Creates a draft contract

Changed on

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.

post/draft-contracts

Request

Request body

subsidiary_idstring uuid required
customer_idstring uuid required

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

namestring required
close_datestring date required
start_datestring date
end_datestring 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.

purchase_order_numberstring

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

shipping_customer_idstring uuid nullable

A UUID, or null to explicitly select nothing. Omitting the field is not the same as sending null.

billing_address_idstring uuid nullable

A UUID, or null to explicitly select nothing. Omitting the field is not the same as sending null.

shipping_address_idstring uuid nullable

A UUID, or null to explicitly select nothing. Omitting the field is not the same as sending null.

Example request

{
  "external_references": [
    {
      "type": "xyzSystemId",
      "id": "234",
      "url": "https://xyzsystempage.com/ids/234"
    }
  ],
  "name": "Acme Corp - Annual subscription",
  "amount": {
    "amount": "1.01",
    "currency": "USD"
  },
  "items": [
    {
      "price": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "interval_months": 1
      },
      "quantity": 1,
      "discount": {
        "amount_off": {
          "amount": "1.01",
          "currency": "USD"
        }
      },
      "declared_ssp": {
        "amount": "1.01",
        "currency": "USD"
      }
    }
  ]
}

Response

OK

idstring uuid required
subsidiary_idstring uuid required
customer_idstring uuid required
namestring required
close_datestring date required
start_datestring date
end_datestring 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.

purchase_order_numberstring

Purchase order number set on the draft. Null when none was set.

shipping_customer_idstring uuid nullable

The customer the draft ships to. Equal to customer_id when the draft ships to its billing customer. Null when no ship-to customer is stored.

Example response

{
  "external_references": [
    {
      "type": "xyzSystemId",
      "id": "234",
      "url": "https://xyzsystempage.com/ids/234"
    }
  ],
  "amount": {
    "amount": "1.01",
    "currency": "USD"
  },
  "items": [
    {
      "price": {
        "amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "interval_months": 1
      },
      "discount": {
        "amount_off": {
          "amount": "1.01",
          "currency": "USD"
        }
      },
      "declared_ssp": {
        "amount": "1.01",
        "currency": "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"
  }
}

Changes

  • c393d0102005Revision changes
    • breaking

      the // response's property type changed from number to string, and format from no format to number for status

    • 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 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