---
title: "Creates an invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Creates an invoice

`POST /invoices`

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.

## Request body

- union
  - object
    - `customer_id` string, uuid, required
    - `subsidiary_id` string, uuid
    - `items` CreateFullInvoiceItemRequest[], required
      - `description` string, required
      - `price` InvoiceItemPriceRequest, required
        - `product_id` string, uuid, 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).
              - …
            - `type` string
          - PercentageDiscount
            - `percentage_off` number, double, required
            - `type` string
        - `amount_per_unit` 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
      - `revenue` ItemRevenue
        - `period` CalendarPeriod
          - `start` string, date, required
          - `end` string, date, required
        - `pattern` 'DAILY' | 'EVEN_PERIOD' — DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
        - `account_code` string — The account code found in the Chart of Accounts
      - `tax_rate` TaxRateWithOptionalAmount
        - `percentage` 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
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
    - `due_date` string, date — If not provided, defaults to the invoice date.
    - `invoice_date` string, date, required
    - `purchase_order_number` string
    - `memo` string
    - `bank_account_id` string, uuid — The ID for the bank account that, should be shown on the invoice. You can find the ID in the UI at /settings/bank-accounts.
    - `external_references` ExternalReference[]
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `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
    - `scope` string
  - object
    - `customer_id` string, uuid, required
    - `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` CreateRevenueRecognitionOnlyInvoiceItemRequest[], required
      - `product_id` string, uuid, required
      - `description` string, required
      - `quantity` 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
      - `revenue` ItemRevenue
        - `period` CalendarPeriod
          - `start` string, date, required
          - `end` string, date, required
        - `pattern` 'DAILY' | 'EVEN_PERIOD' — DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
        - `account_code` string — The account code found in the Chart of Accounts
      - `external_references` ExternalReference[], required
        - `type` string, required
        - `id` string, required
        - `url` string, uri
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
    - `external_references` ExternalReference[], required
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `subsidiary_id` string, uuid
    - `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
    - `scope` string
  - object
    - `customer_id` string, uuid, required
    - `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` CreateRevenueRecognitionOnlyInvoiceItemRequest[], required
      - `product_id` string, uuid, required
      - `description` string, required
      - `quantity` 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
      - `revenue` ItemRevenue
        - `period` CalendarPeriod
          - `start` string, date, required
          - `end` string, date, required
        - `pattern` 'DAILY' | 'EVEN_PERIOD' — DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
        - `account_code` string — The account code found in the Chart of Accounts
      - `external_references` ExternalReference[], required
        - `type` string, required
        - `id` string, required
        - `url` string, uri
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
    - `external_references` ExternalReference[], required
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `subsidiary_id` string, uuid
    - `scope` string

## Response `200`

OK

- Invoice
  - `id` string, uuid, required
  - `subsidiary_id` string, uuid, required
  - `invoice_number` string, required
  - `customer_id` string, uuid, required
  - `contract_id` string, uuid
  - `items` InvoiceItem[], required
    - `id` string, uuid, required
    - `description` string, required
    - `revenue` ItemRevenue, required
      - `period` CalendarPeriod
        - `start` string, date, required
        - `end` string, date, required
      - `pattern` 'DAILY' | 'EVEN_PERIOD' — DAILY means that the revenue is divided equally per day in the revenue period. EVEN_PERIOD means that the revenue is divided equally for each calendar month in the revenue period.
      - `account_code` string — The account code found in the Chart of Accounts
    - `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
    - `total_discount` 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
    - `taxed_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
    - `gross_rate` 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
    - `quantity` number, required
    - `product_id` string, uuid, required
    - `external_references` ExternalReference[], required
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `fields` object[]
      - `field_id` string, uuid, required
      - `field_value_id` string, uuid, required
  - `due_date` string, date, required
  - `invoice_date` string, date, required
  - `address` Address
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required — State or province code (e.g. 'TN', 'CA' for US; 'ON' for Canada). Required when address is provided.
    - `zip_code` string, required
    - `country` string, required — Two-letter country code (ISO 3166-1 alpha-2).
  - `customer_address` Address
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required — State or province code (e.g. 'TN', 'CA' for US; 'ON' for Canada). Required when address is provided.
    - `zip_code` string, required
    - `country` string, required — Two-letter country code (ISO 3166-1 alpha-2).
  - `shipping_address` Address
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required — State or province code (e.g. 'TN', 'CA' for US; 'ON' for Canada). Required when address is provided.
    - `zip_code` string, required
    - `country` string, required — Two-letter country code (ISO 3166-1 alpha-2).
  - `bank_account` InvoicingBankAccount
    - `id` string, uuid, required
    - `ach_account` string, required
    - `ach_routing` string, required
    - `bank_name` string, required
    - `bank_address` string
    - `swift_code` string
    - `payment_instructions` string
  - `status` 'UNPAID' | 'PAID' | 'PARTIALLY_PAID' | 'UNBILLED' | 'CREDITED' | 'PARTIALLY_CREDITED', required
  - `net_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
  - `amount_due` 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` 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
  - `payment_terms` integer, required
  - `subtotal` 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_discount` 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
  - `purchase_order_number` string
  - `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
  - `taxed_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
  - `memo` string
  - `overdue` boolean, required
  - `external_references` ExternalReference[]
    - `type` string, required
    - `id` string, required
    - `url` string, uri
  - `updated_at` string, date-time, required — ISO 8601 timestamp in UTC timezone (must end with 'Z')
  - `sent_at` string, 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.

## 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)