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

Invoices

Creates an invoice

Changed on Nov 3, 2026

A matching creation approval workflow returns HTTP 202 with invoice_id, approval_request_id, and status PENDING. This is a proposal, not a created invoice. Retrieve its contents using retrieve-an-invoice-creation-proposal. For approval proposals, pass idempotency_key on the initial call and retain it across retries. The key is optional; each call without one creates a new submission, including retries. The key does not deduplicate legacy creation when approvals are disabled or the invoice belongs to a contract. A rejected proposal remains closed; a deliberate new invoice uses a new key.

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

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

The REVENUE_RECOGNITION_ONLY scope is intended for situations where the invoice is issued from another system and only needs to be recorded in Rillet for accounting purposes. In this workflow, users must provide the invoice number 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/invoices

Request

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

Query parameters

idempotency_keystring uuid

Stable key for retries of an approval proposal. Ignored when approvals are disabled or the invoice belongs to a contract. Use a new key for a distinct proposal.

replaces_request_idstring uuid

Current approval request to replace when deliberately revising a held proposal using the same key.

Request body

Example request

{
  "items": [
    {
      "price": {
        "discount": {
          "amount_off": {
            "amount": "1.01",
            "currency": "USD"
          }
        },
        "amount_per_unit": {
          "amount": "1.01",
          "currency": "USD"
        }
      },
      "revenue": {
        "account_code": "11112"
      },
      "tax_rate": {
        "percentage": "0",
        "tax_amount": {
          "amount": "1.01",
          "currency": "USD"
        },
        "country": "US"
      }
    }
  ],
  "purchase_order_number": "1",
  "external_references": [
    {
      "type": "xyzSystemId",
      "id": "234",
      "url": "https://xyzsystempage.com/ids/234"
    }
  ],
  "exchange_rate": {
    "base": "USD",
    "target": "USD"
  }
}

Response

idstring uuid required

subsidiary_idstring uuid required

invoice_numberstring required

customer_idstring uuid required

contract_idstring uuid

due_datestring date required

invoice_datestring date required

shipping_customer_idstring uuid nullable

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

payment_termsinteger required

purchase_order_numberstring

memostring

overdueboolean required

metadataobject

Invoice metadata values keyed by metadata definition key.

updated_atstring date-time required

ISO 8601 timestamp in UTC timezone (must end with 'Z')

sent_atstring date-time

ISO 8601 timestamp in UTC timezone (must end with 'Z') marking when the invoice was first sent to the customer from Rillet (either by a user action or by automation). Null if the invoice has never been sent from Rillet.

Example response

{
  "invoice_number": "INV01",
  "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"
        }
      ]
    }
  ],
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Nashville",
    "state": "TN",
    "zip_code": "37201",
    "country": "US"
  },
  "customer_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"
  },
  "net_amount": {
    "amount": "1.01",
    "currency": "USD"
  },
  "amount_due": {
    "amount": "1.01",
    "currency": "USD"
  },
  "total": {
    "amount": "1.01",
    "currency": "USD"
  },
  "subtotal": {
    "amount": "1.01",
    "currency": "USD"
  },
  "total_discount": {
    "amount": "1.01",
    "currency": "USD"
  },
  "purchase_order_number": "1",
  "exchange_rate": {
    "base": "USD",
    "target": "USD"
  },
  "taxed_amount": {
    "amount": "1.01",
    "currency": "USD"
  },
  "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
  the ////// request property type changed from object to no type
- breaking
  the response property / became nullable for the status
- breaking
  the response property / became nullable for the status
- breaking
  the response property / became optional for the status
- breaking
  the response's property type changed from object 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 object to no type for status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the 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 query request parameter replaces_request_id
- 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 PROGRESS enum value to the request property ///////
- info
  added the new PROGRESS enum value to the request property ///////
- info
  added the new PROGRESS enum value to the request property ///////
- info
  the ////// request property's min was decreased from 0.00 to 0.00
- info
  the ////// request property's min was decreased from 0.00 to 0.00
- 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 to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added the required property to the response with the status
- info
  added the success response with the status

Operation history