---
title: "Update invoice header, line items, and dimensions"
method: PATCH
path: "/invoices/{id}"
tags: ["invoices"]
---

# Update invoice header, line items, and dimensions

`PATCH /invoices/{id}`

Updates an invoice along with its line items and dimensions.

### Features
- Update invoice header fields (date, amount, vendor, notes, etc.)
- Create new line items (omit `id`)
- Update existing line items (include `id`)
- Set, update, or remove header and item-level dimensions
- Update custom metadata fields at header and item level (requires account-level custom field spec configuration)

### Use Cases
- Invoice corrections
- Invoice reconciliation with updated line items
- Adding or updating dimensions after initial invoice creation
- Multi-field updates in a single request

## Path parameters

- `id` string, required

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string

## Request body

- object
  - `ottimate_location_id` integer — The ID of the location for this invoice.
  - `erp_vendor_id` string — The ERP ID of the vendor for this invoice.
  - `erp_vendor_name` string — ERP vendor name. Required when creating a new vendor via erp_vendor_id.
  - `invoice_number` string
  - `invoice_date` string, date
  - `due_date` string, date
  - `posting_date` string, date
  - `total_amount` number, double
  - `total_tax` number, double
  - `discount_amount` number, double
  - `purchase_order` string
  - `notes` string
  - `currency` string
  - `type` 'invoice' | 'credit_memo' — Type of document.
  - `dimensions` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaDimensions — Header-level dimension mappings. Keys are dimension types (e.g., 'DEPARTMENT') and values are `erp_dimension_id` strings from the `GET /dimensions` endpoint. Replaces all header dimensions with the provided set. Omit the field entirely to preserve existing dimensions. Pass `{}` to clear all header dimensions.
  - `custom_fields` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaCustomFields — Header-level custom metadata fields. Replaces the stored custom fields with the provided object — any keys not included are reset to their configured default values. **Requirements**: Custom fields must be configured for your account before use. Returns a `400` error if no spec is found or if unrecognised keys are sent. **Behaviour**: Omit the field entirely to preserve existing custom fields.
  - `items` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaItemsItems[] — Line items to create or update. Include `id` to update an existing item, omit `id` to create a new item.
    - `id` integer — Existing item ID to update. Omit to create a new item.
    - `item` integer — Inventory item ID
    - `name` string
    - `sku` string
    - `quantity` number, double
    - `price` number, double
    - `is_taxed` boolean
    - `dimensions` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaItemsItemsDimensions — Item-level dimension mappings. Keys are dimension types, values are `erp_dimension_id` strings. Merges with existing dimensions. Set a value to `null` to remove only that dimension. Pass `{}` or omit the field to preserve existing dimensions.
    - `custom_fields` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaItemsItemsCustomFields — Item-level custom metadata fields. Replaces the stored item custom fields — omitted keys are reset to their configured default values. **Requirements**: Invoice item custom fields must be configured for your account before use. Returns a `400` error if no spec is found or if unrecognised keys are sent.
  - `image_urls` string[] — Replaces all existing invoice images with the provided URLs. Pass an empty array to delete all images. Omit the field entirely to leave existing images unchanged. Supported formats: PDF, JPG, JPEG, PNG.
  - `raw_images` InvoicesIdPatchRequestBodyContentApplicationJsonSchemaRawImagesItems[] — Replaces all existing invoice images with the provided base64-encoded images. Pass an empty array to delete all images. Omit the field entirely to leave existing images unchanged. Supported formats: PDF, JPG, JPEG, PNG.
    - `filename` string, required — Original filename including extension (e.g. invoice.pdf). Used to determine file format.
    - `data` string, required — Base64-encoded image content.

## Response `200`

Invoice updated successfully

- InvoiceDetailObject
  - `version` string — API version
  - `id` string, required — Unique invoice identifier
  - `invoice_number` string — Invoice number from vendor
  - `ottimate_vendor_name` string — Ottimate vendor name. With X-API-Version: 1.1.0 this is the human-readable vendor name.
  - `ottimate_vendor_id` integer, nullable — Ottimate vendor ID. For X-API-Version: 1.1.0 this is an integer matching the `id` returned by GET /vendors (usable with GET /vendors/{id}); for 1.0.0/unversioned it is returned as a string (the operational vendor id). Null when the invoice has no vendor mapping.
  - `erp_vendor_id` string — ERP vendor id (the accounting system's own vendor code).
  - `erp_vendor_name` string — ERP vendor display name.
  - `ottimate_location_name` string — Location name
  - `ottimate_location_id` string — Ottimate location (restaurant) ID.
  - `custom_fields` InvoiceDetailObjectCustomFields — Custom header field key/value pairs configured for the company.
  - `invoice_date` string, date — Date invoice was issued
  - `due_date` string, date — Payment due date
  - `total_amount` number, double — Total invoice amount
  - `total_tax` number, double — Total tax amount
  - `currency` string — Currency code (ISO 4217)
  - `outstanding_balance` number, double — Remaining unpaid amount
  - `type` 'invoice' | 'credit_memo' | 'other' — Type of invoice document
  - `status` 'processing' | 'needs-attention' | 'pending-approval' | 'ready-for-export' | 'exported' | 'inactive', required — Invoice processing status
  - `sub_status` 'deleted' | 'merged' | 'archived' | 'duplicate' — Reason why the invoice is inactive. Only present when status is 'inactive', null otherwise.
  - `payment_status` 'paid' | 'partial' | 'unpaid', required — Payment status
  - `payment_info` InvoiceDetailObjectPaymentInfo — Payment information for the invoice. Always present in the response; contains an empty object ({}) when payment_status is not 'paid'.
    - `payment_method` string — Method used for payment
    - `reference` string — Payment reference number
  - `purchase_order` string — Associated purchase order number
  - `created_at` string, date-time, required — Timestamp when invoice was created
  - `created_at_utc` string, date-time, nullable — UTC equivalent of created_at. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `approved_date` string, date-time, nullable — Date when invoice was approved
  - `approved_date_utc` string, date-time, nullable — UTC equivalent of approved_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `posting_date` string, date, nullable — Date when invoice was posted
  - `exported_date` string, date-time — Date when invoice was exported
  - `exported_date_utc` string, date-time, nullable — UTC equivalent of exported_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `error` string — Error message if invoice is flagged
  - `notes` string, nullable — Free-text notes on the invoice.
  - `image_errors` string, nullable — Errors encountered while processing/uploading invoice images, if any. Empty string when there are none.
  - `url` string — URL to view the invoice in the Ottimate dashboard
  - `images` InvoiceDetailObjectImagesItems[] — List of invoice images
    - `id` integer — Unique image identifier
    - `url` string — CDN URL to the invoice image
  - `dimensions` InvoiceDetailObjectDimensions — Header-level dimension mappings. Contains accounting dimensions assigned to the invoice header (e.g., Department, Class, Location).
  - `items` InvoiceLineItemObject[] — Line item details with matched catalog entry information for this invoice. Always present in the response (unlike the list endpoint, where this requires expand=items).
    - `id` string — Unique invoice line item identifier
    - `ottimate_item_id` string — Ottimate catalog item identifier for this line
    - `name` string, nullable — Item name as recorded on the line
    - `display_name` string, nullable — Display name for the item
    - `sku` string, nullable — SKU for the item on this line
    - `type` string, nullable — Line item type
    - `quantity` number, double — Quantity purchased on this line
    - `unit` string, nullable — Unit of measure label for the quantity
    - `unit_price` number, double — Price per unit
    - `line_total` number, double — Total amount for this line (quantity * unit_price)
    - `charge_type` string, nullable — Charge type code for this line, if any
    - `is_taxed` boolean — Whether this line is taxed
    - `pack_size` string, nullable — Pack size label for the item
    - `uom` string, nullable — Unit of measure code
    - `catalog_entry` InvoiceLineItemObjectCatalogEntry — Matched catalog entry for this line item. Null when the line item has no catalog match.
      - `id` string — Catalog entry identifier
      - `ottimate_company_id` integer — Company ID owning this catalog entry
      - `reference_id` string, nullable — Unique reference key for the catalog entry
      - `catalog_unique_key` string, nullable — Catalog-wide unique key for the entry
      - `description` string, nullable — Catalog entry description
      - `original_description` string, nullable — Original description as received from the vendor
      - `sku` string, nullable — SKU code
      - `upc` string, nullable — UPC code
      - `size` string, nullable — Pack size for the catalog entry
      - `uom` string, nullable — Unit of measure
      - `price` number, double, nullable — Catalog price
      - `unit_price` number, double, nullable — Catalog unit price
      - `last_purchased_price` number, double, nullable — Most recent purchase price recorded for this catalog entry
      - `erp_vendor_id` string, nullable — ERP vendor id sourced from the originating accounting system
      - `ottimate_vendor_name` string, nullable — Ottimate vendor name for this catalog entry
      - `is_split_case` boolean — Whether the catalog entry supports split-case buying
      - `authorized_vendor` boolean — Whether the vendor is authorized for this catalog entry
      - `last_purchased_date` string, date, nullable — Date of the most recent purchase of this catalog entry
      - `last_purchased_date_utc` string, date-time, nullable — UTC equivalent of last_purchased_date
      - `created_date` string, date, nullable — Date the catalog entry was created
      - `created_date_utc` string, date-time, nullable — UTC equivalent of created_date
      - `last_modified_date` string, date, nullable — Date the catalog entry was last modified
      - `last_modified_date_utc` string, date-time, nullable — UTC equivalent of last_modified_date
      - `dimensions` InvoiceLineItemObjectCatalogEntryDimensions — POS dimensions for the catalog entry. Present only when the matched catalog entry has dimension data.
      - `properties` InvoiceLineItemObjectCatalogEntry — recursive
      - `display_name` string — Catalog entry display name. Present only when the matched catalog entry has a display name.
      - `prices` InvoiceLineItemObjectCatalogEntryPricesItems[] — Catalog price history. Present only when the matched catalog entry has price history.
      - `allowances` InvoiceLineItemObjectCatalogEntryAllowancesItems[] — Catalog allowances. Present only when the matched catalog entry has allowances.
    - `custom_fields` InvoiceLineItemObjectCustomFields — Custom field key/value pairs configured on the line item
    - `dimensions` InvoiceLineItemObjectDimensions — Line-item-level dimension mappings, in the same shape as the invoice header's dimensions.
  - `gl_splits` InvoiceDetailObjectGlSplitsItems[], nullable — GL account splits for the invoice. Returns real splits if they exist, otherwise falls back to virtual splits derived from vendor split rules. null when no splits or rules are configured.
    - `memo` string, nullable — Optional note on the split
    - `amount` string — Split amount formatted to 2 decimal places
    - `custom_fields` InvoiceDetailObjectGlSplitsItemsCustomFields — Custom metadata fields for this split
    - `dimensions` InvoiceDetailObjectGlSplitsItemsDimensions — Accounting dimensions for this split. Same structure as header-level dimensions. Keys are dimension type codes.
  - `items_processing_result` InvoiceDetailObjectItemsProcessingResult — Result of items processing (only present in PATCH response when items were included in request)
    - `success` InvoiceDetailObjectItemsProcessingResultSuccess — Map of request array index to created/updated item ID
    - `failure` InvoiceDetailObjectItemsProcessingResultFailure — Map of request array index to error message
    - `status` 'success' | 'partial_success' | 'failure' — Overall processing status: success (all items processed), partial_success (some failed), failure (all failed)
  - `history` InvoiceDetailObjectHistoryItems[] — Audit history of the invoice. Only present when expand=history is passed as a query parameter.
    - `id` string — History log entry ID
    - `date` string, date-time — Timestamp of the history event
    - `date_utc` string, date-time, nullable — UTC equivalent of date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
    - `reason` string — Type of action that occurred
    - `message` string — Details about the action
    - `user` InvoiceDetailObjectHistoryItemsUser — User who performed the action
      - `id` integer — User ID
      - `email` string — Email address
      - `first_name` string — First name
      - `last_name` string — Last name
  - `last_modified_date` string, date-time, nullable — Timestamp when invoice was last modified
  - `last_modified_date_utc` string, date-time, nullable — UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".
  - `last_modified_user` InvoiceDetailObjectLastModifiedUser — User who last modified the invoice
    - `id` integer
    - `email` string, email
    - `first_name` string
    - `last_name` string

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `403` — Forbidden - Access denied or insufficient permissions
- `404` — Not found - Resource does not exist
- `412` — Precondition failed - concurrent modification
- `500` — Internal server error - Server-side processing error

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)