Retrieve detailed information for a specific invoice | Ottimate Developer Documentation

curl -G https://api.ottimate.com/v1/invoices/racc_90832490382904802384 \
     -H "X-Api-Key: your-api-key-here" \
     -H "X-API-Version: 1.0.0" \
     -H "Authorization: Bearer <token>" \
     --data-urlencode expand=gl_splits,history

{
  "id": "124426270",
  "status": "ready-for-export",
  "payment_status": "unpaid",
  "created_at": "2024-12-01T00:30:00-08:00",
  "version": "1.0.0",
  "invoice_number": "INV-2024-00456",
  "ottimate_vendor_name": "Sysco Foods Corp",
  "ottimate_location_name": "Main Kitchen",
  "invoice_date": "2024-12-01",
  "due_date": "2024-12-31",
  "total_amount": 1250,
  "total_tax": 100,
  "currency": "USD",
  "outstanding_balance": 1250,
  "type": "invoice",
  "purchase_order": "PO-2024-001",
  "created_at_utc": "2024-12-01T08:30:00.000000Z",
  "exported_date": null,
  "exported_date_utc": null,
  "error": null,
  "url": "https://app.ottimate.com/#/invoice/124426270/",
  "images": [
    {
      "id": 12345,
      "url": "https://cdn.ottimate.com/invoices/image-12345.jpg"
    }
  ],
  "dimensions": {
    "DEPARTMENT": {
      "id": "dim_kVQu__-iUwk",
      "erp_dimension_id": "erp_dim_dept123",
      "name": "Sales",
      "code": "SALES",
      "display_name": "Sales Department"
    },
    "CLASS": {
      "id": "dim_kVQu__-asjk",
      "erp_dimension_id": "erp_dim_dept1",
      "name": "Retail",
      "code": "RTL",
      "display_name": "Retail Operations"
    }
  },
  "last_modified_date": "2024-12-02T02:15:00-08:00",
  "last_modified_date_utc": "2024-12-02T10:15:00.000000Z",
  "last_modified_user": {
    "id": 42,
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }
}

Returns comprehensive details for a single invoice, including full metadata, vendor information, location, payment status, error details (if any), and export tracking status.

Authentication

AuthorizationBearer

OAuth2 authentication flows. Auth server URLs will vary by environment

Path parameters

idstringRequired

Invoice ID - Unique identifier of the invoice to retrieve

Query parameters

expandstringOptional

Comma-separated list of fields to expand. Options: history, gl_splits. Use history to include the full audit log. Use gl_splits to include GL account splits (real splits or virtual splits derived from line-item mappings).

Response

Successful response with invoice details

idstring

Unique invoice identifier

statusenum

Invoice processing status

payment_statusenum

Payment status

created_atstringformat: "date-time"

Timestamp when invoice was created

versionstringOptional

API version

invoice_numberstringOptional

Invoice number from vendor

ottimate_vendor_namestringOptional

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

ottimate_vendor_idinteger or nullOptional

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_idstringOptional

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

erp_vendor_namestringOptional

ERP vendor display name.

ottimate_location_namestringOptional

Location name

ottimate_location_idstringOptional

Ottimate location (restaurant) ID.

custom_fieldsobjectOptional

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

invoice_datestringOptionalformat: "date"

Date invoice was issued

due_datestringOptionalformat: "date"

Payment due date

total_amountdoubleOptional>=0

Total invoice amount

total_taxdoubleOptional>=0

Total tax amount

currencystringOptionalDefaults to USD

Currency code (ISO 4217)

outstanding_balancedoubleOptional>=0

Remaining unpaid amount

typeenumOptional

Type of invoice document

sub_statusenum or nullOptional

Reason why the invoice is inactive. Only present when status is 'inactive', null otherwise.

payment_infoobjectOptional

Payment information for the invoice. Always present in the response; contains an empty object () when payment_status is not ‘paid’.

purchase_orderstringOptional

Associated purchase order number

created_at_utcstring or nullOptionalformat: "date-time"

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

approved_datestring or nullOptionalformat: "date-time"

Date when invoice was approved

approved_date_utcstring or nullOptionalformat: "date-time"

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

posting_datestring or nullOptionalformat: "date"

Date when invoice was posted

exported_datestringOptionalformat: "date-time"

Date when invoice was exported

exported_date_utcstring or nullOptionalformat: "date-time"

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

errorstringOptional

Error message if invoice is flagged

notesstring or nullOptional

Free-text notes on the invoice.

image_errorsstring or nullOptional

Errors encountered while processing/uploading invoice images, if any. Empty string when there are none.

urlstringOptional

URL to view the invoice in the Ottimate dashboard

imageslist of objectsOptional

List of invoice images

dimensionsobjectOptional

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

itemslist of objectsOptional

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

gl_splitslist of objects or nullOptional

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.

items_processing_resultobjectOptional

Result of items processing (only present in PATCH response when items were included in request)

historylist of objectsOptional

Audit history of the invoice. Only present when expand=history is passed as a query parameter.

last_modified_datestring or nullOptionalformat: "date-time"

Timestamp when invoice was last modified

last_modified_date_utcstring or nullOptionalformat: "date-time"

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

last_modified_userobject or nullOptional

User who last modified the invoice

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

Authentication

Path parameters

Headers

Query parameters

Response

Errors