Sign in

v1

latestOpenAPI 3.1.02026-08-0458234268.6 KB
invoices

Retrieve detailed information for a specific invoice

Returns comprehensive details for a single invoice including all metadata, processing information, and payment status.

📋 What You Get

This endpoint provides the complete invoice record with:

  • 🧾 Full invoice metadata (dates, amounts, status)
  • 🏢 Vendor information and contact details
  • 📍 Location where invoice was received
  • 💳 Payment information (when invoice is paid)
  • ⚠️ Error details (if invoice has processing issues)
  • 📤 Export tracking (integration status)

🔍 Usage Examples

Basic Retrieval

curl -H "X-Api-Key: your-api-key" \
     https://api.acme.com/v1/invoices/550e8400-e29b-41d4-a716-446655440000

With Version Header

curl -H "X-Api-Key: your-api-key" \
     -H "X-API-Version: 1.0.0" \
     https://api.acme.com/v1/invoices/550e8400-e29b-41d4-a716-446655440000

⚡ Performance Notes

  • Response time: Typically < 100ms
  • Caching: Results cached for 5 minutes
  • Rate limits: Applies to your overall API quota

💡 Tip: Use this endpoint after getting results from the list endpoint to get full details for specific invoices.

get/invoices/{id}

Path parameters

idstring required

Invoice UUID - Unique identifier of the invoice to retrieve

Query parameters

expandstring

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

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.

Response

Successful response with invoice details

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

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

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