---
title: "Updates an invoice"
method: PUT
path: "/invoices/{invoice_id}"
tags: ["Invoices"]
---

# Updates an invoice

`PUT /invoices/{invoice_id}`

IMPORTANT: This is a full-replace operation (PUT semantics). All fields must be
included in the request body — omitting any field will set it to null, wiping
existing data. Always call retrieve-an-invoice first to fetch the current record,
then include ALL existing fields in your update request along with your changes.

## Path parameters

- `invoice_id` string, required

## Request body

- union
  - object
    - `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, required — The ID for the bank account that should be shown on the invoice. You can also find the ID in the Rillet UI at /settings/bank-accounts.
    - `external_references` ExternalReference[]
      - `type` string, required
      - `id` string, required
      - `url` string, uri
    - `scope` string
  - object
    - `invoice_date` string, date, required
    - `due_date` string, date — Defaults to invoice_date if not provided
    - `invoice_number` string — Optional - updates the invoice number if provided
    - `items` UpdateRevenueRecognitionOnlyInvoiceItemRequest[], required
      - `id` string, uuid, required — The existing invoice item ID to update. Must match an item on the original invoice.
      - `description` string
      - `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
      - `fields` object[]
        - `field_id` string, uuid, required
        - `field_value_id` string, uuid, required
    - `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

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