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

# Updates invoice taxes

`POST /invoices/{invoice_id}/taxes`

## Request

- Base URL: `https://api.rillet.com`
- URL: `https://api.rillet.com/invoices/{invoice_id}/taxes`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/rillet/apis/rillet-accounting-api/docs/invoices/:invoice_id/taxes/post.ts> (a function with typed inputs; its response is checked against the schema)

Recalculates or replaces tax lines on an existing invoice using the supplied tax payload.
Use after changing taxable addresses or when integrating an external tax engine result.
Returns `400` when the supplied taxes would turn an invoice total that is zero or positive into a negative
total. Invoices whose total is already negative can still be updated.

## Path parameters

- `invoice_id` string, required

## Request body

- UpdateTaxesRequest
  - `taxes_calculated_at` string, date-time, required: ISO 8601 timestamp in UTC timezone (must end with 'Z')
  - `items` UpdateItemTaxesRequest[], required
    - `id` string, uuid, required
    - `tax_rates` TaxRate[]
      - `percentage` string, 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

## Response `200`

OK

- union
  - 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' | 'PROGRESS': DAILY divides revenue equally per day. EVEN_PERIOD divides revenue equally per calendar month. PROGRESS uses a progress plan; the supported measure MILESTONES recognizes allocated revenue on milestone completion and requires a one-time price. FULL contract creation supports an explicit progress plan or snapshots the referenced product's template. Existing non-progress behavior is unchanged.
        - `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` string, 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, nullable
      - `city` string, required
      - `state` string, nullable: State or province code. Required for United States addresses and optional where it does not apply.
      - `zip_code` string, required
      - `country` string, required: Two-letter country code (ISO 3166-1 alpha-2).
    - `customer_address` CustomerAddress
      - `id` string, uuid: Stable ID of a stored customer address. Use it as billing_address_id or shipping_address_id on contracts and invoices. On customer update, send it to keep or edit an existing address; omit it to add a new address. Omitted in responses when the address no longer exists on the customer.
      - `line1` string, required
      - `line2` string, nullable
      - `city` string, required
      - `state` string, nullable: State or province code. Required for United States addresses and optional where it does not apply.
      - `zip_code` string, required
      - `country` string, required: Two-letter country code (ISO 3166-1 alpha-2).
    - `shipping_address` CustomerAddress
      - `id` string, uuid: Stable ID of a stored customer address. Use it as billing_address_id or shipping_address_id on contracts and invoices. On customer update, send it to keep or edit an existing address; omit it to add a new address. Omitted in responses when the address no longer exists on the customer.
      - `line1` string, required
      - `line2` string, nullable
      - `city` string, required
      - `state` string, nullable: State or province code. Required for United States addresses and optional where it does not apply.
      - `zip_code` string, required
      - `country` string, required: Two-letter country code (ISO 3166-1 alpha-2).
    - `shipping_customer_id` string, 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.
    - `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
    - `metadata` object: Invoice metadata values keyed by metadata definition key.
    - `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.
    - `email_selection` EmailSelection, required
      - `mode` 'ALL_CUSTOMER_EMAILS' | 'SELECTED_EMAILS', required: ALL_CUSTOMER_EMAILS: sent to every email on the billing customer at the time of sending, including emails added later, each as its own type. SELECTED_EMAILS: sent only to recipients.
      - `recipients` EmailRecipient[]
        - `customer_email_id` string, uuid, required: ID of one of the billing customer's emails.
        - `recipient_type` 'MAIN_SENDER' | 'CC' | 'BCC', required: How the email receives the invoice: MAIN_SENDER is To, CC and BCC are copies.
  - InvoiceUpdateProposal: Proposed edits awaiting approval. These changes have not been applied to the invoice.
    - `invoice_id` string, uuid, required
    - `approval_request_id` string, uuid, required
    - `status` 'PENDING', required

## Other responses

- `202`: Tax changes are held for approval; effective invoice amounts are unchanged.
- `default`: Error

## Changes

- **2026-11-03** `c393d0102005`: 20 breaking, 10 warning, 1 info
  - the `items/items/tax_rates/items/allOf[#/components/schemas/TaxRateWithOptionalAmount]/percentage` request property type changed from `number` to `string`, and format from no format to `number`
  - added `#/components/schemas/Invoice, #/components/schemas/InvoiceUpdateProposal` to the response body `oneOf` list for the response status `200`
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `amount_due` from the response with the `200` status
  - …27 more

[Operation history](https://skmtc.dev/rillet/apis/rillet-accounting-api/changes/invoices/:invoice_id/taxes/post.md)

---

[API](https://skmtc.dev/rillet/apis/rillet-accounting-api.md) - [All operations](https://skmtc.dev/rillet/apis/rillet-accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rillet/apis/rillet-accounting-api/revisions/c393d0102005?raw)