v1

latestOpenAPI 3.1.02026-08-0458234268.6 KB

invoices

Update invoice header, line items, and dimensions

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

patch/invoices/{id}

Path parameters

idstring required

Invoice ID to update

Headers

Authorizationstring required

OAuth2 authentication flows. Auth server URLs will vary by environment

X-Api-Keystring required

API key for authentication

X-API-Versionstring

API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

Request body

ottimate_location_idinteger

The ID of the location for this invoice.

erp_vendor_idstring

The ERP ID of the vendor for this invoice.

erp_vendor_namestring

ERP vendor name. Required when creating a new vendor via erp_vendor_id.

invoice_numberstring

invoice_datestring date

due_datestring date

posting_datestring date

total_amountnumber double

total_taxnumber double

discount_amountnumber double

purchase_orderstring

notesstring

currencystring

type'invoice' | 'credit_memo'

Type of document.

dimensionsInvoicesIdPatchRequestBodyContentApplicationJsonSchemaDimensions

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_fieldsInvoicesIdPatchRequestBodyContentApplicationJsonSchemaCustomFields

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.

image_urlsstring[]

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.

Response

Invoice updated successfully

versionstring

API version

idstring required

Unique invoice identifier

numberstring

Invoice number from vendor

ottimate_vendor_namestring

Ottimate vendor name. With X-API-Version: 1.1.0 this is the human-readable vendor name.

ottimate_vendor_idinteger 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_idstring

ERP vendor id (the accounting system's own vendor code).

erp_vendor_namestring

ERP vendor display name.

ottimate_location_namestring

Location name

ottimate_location_idstring

Ottimate location (restaurant) ID.

custom_fieldsInvoiceDetailObjectCustomFields

Custom header field key/value pairs configured for the company.

invoice_datestring date

Date invoice was issued

due_datestring date

Payment due date

total_amountnumber double

Total invoice amount

total_taxnumber double

Total tax amount

currencystring

Currency code (ISO 4217)

outstanding_balancenumber double

Remaining unpaid amount

type'invoice' | 'credit_memo' | 'other'

Type of invoice document

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

purchase_orderstring

Associated purchase order number

created_atstring date-time required

Timestamp when invoice was created

created_at_utcstring date-time nullable

UTC equivalent of created_at. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".

exported_datestring date-time

Date when invoice was exported

exported_date_utcstring date-time nullable

UTC equivalent of exported_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".

errorstring

Error message if invoice is flagged

urlstring

URL to view the invoice in the Ottimate dashboard

dimensionsInvoiceDetailObjectDimensions

Header-level dimension mappings. Contains accounting dimensions assigned to the invoice header (e.g., Department, Class, Location).

last_modified_datestring date-time nullable

Timestamp when invoice was last modified

last_modified_date_utcstring date-time nullable

UTC equivalent of last_modified_date. ISO 8601 with Z suffix, e.g. "2025-05-20T15:17:35.652584Z".