> This page is for version V1 (default). > For other versions, use one of these documentation indexes: > - V1 (default): https://docs.ottimate.com/v-1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ottimate.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ottimate.com/_mcp/server. # Catalog Variances Catalog variances help you identify pricing discrepancies between your catalog prices and actual invoice charges. Ottimate calculates the variance by comparing the invoiced price against the effective catalog price (accounting for any applicable allowances). A positive variance indicates overbilling (invoice price higher than expected), while a negative variance indicates underbilling (invoice price lower than expected). ## Common Workflows 1. [**Fetching Purchase History for a Catalog Entry**](#fetching-purchase-history-for-a-catalog-entry) - Get invoice items and purchase history for a specific catalog item 2. [**Listing Catalog Variances**](#listing-catalog-variances) - Retrieve catalog entries with price variance summaries --- ## Fetching Purchase History for a Catalog Entry The most common use case is retrieving all invoice items associated with a specific catalog entry. This provides a convenient way to get the complete purchase history for any catalog item, including pricing details and variance information. ### Endpoint ```http GET /v1/catalog/variances/{id}/invoice-items ``` ### Example Request ```http GET /v1/catalog/variances/cte_12345/invoice-items?page=1&limit=20 ``` ### Response ```json { "count": 5, "results": [ { "id": 98765, "invoice_id": 54321, "item_name": "Roma Tomatoes 6CT", "price": 27.5, "quantity": 10, "invoice_date": "2024-12-01", "price_variance": 2.51, "effective_price": 24.99 }, { "id": 98760, "invoice_id": 54310, "item_name": "Roma Tomatoes 6CT", "price": 26.99, "quantity": 12, "invoice_date": "2024-11-15", "price_variance": 2.0, "effective_price": 24.99 } ] } ``` ### Path Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------- | | `id` | String | Yes | The catalog entry ID (e.g., `cte_12345`) | ### Query Parameters | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------------------- | | `page` | Integer | No | Page number for pagination | | `limit` | Integer | No | Number of results per page | ### Invoice Item Fields | Field | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | `id` | Ottimate-generated ID for the invoice line item | | `invoice_id` | Ottimate-generated invoice identifier. Use with `GET /v1/invoices/{invoice_id}` for full details | | `item_name` | Item name extracted from the invoice | | `price` | Actual item price on the invoice | | `quantity` | Quantity purchased | | `invoice_date` | Date of the invoice | | `price_variance` | Difference between invoice price and effective catalog price. Positive = overbilling, negative = underbilling | | `effective_price` | Catalog price minus any applicable allowances and discounts | --- ## Listing Catalog Variances Retrieve catalog entries with aggregated price variance information from invoice items. By default, returns all items that had purchases in the specified period, including items with zero variance. ### Endpoint ```http GET /v1/catalog/variances ``` ### Example Request ```http GET /v1/catalog/variances?ottimate_company_id=15196&variance_only=true&page=1&limit=20 ``` ### Response ```json { "count": 15, "results": [ { "id": "12345", "ottimate_company_id": 15196, "item_name": "Roma Tomatoes 6CT", "price": 27.0, "unit_price": 4.5, "pack_size": "6 CT", "case_size": "6 CT", "erp_vendor_name": "Sysco Foods", "last_invoice_item": { "id": 98765, "price": 27.5, "invoice_date": "2024-12-01", "price_variance": 2.51, "effective_price": 24.99 } }, { "id": "12346", "ottimate_company_id": 15196, "item_name": "Chicken Breast 10lb Case", "price": 90.0, "unit_price": 8.99, "pack_size": "10 LB", "case_size": "10 LB", "erp_vendor_name": "US Foods", "last_invoice_item": { "id": 98766, "price": 85.0, "invoice_date": "2024-11-28", "price_variance": -4.99, "effective_price": 89.99 } } ] } ``` ### Query Parameters | Parameter | Type | Required | Description | | --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- | | `ottimate_company_id` | Integer | Yes | The Ottimate-assigned company ID | | `variance_only` | Boolean | No | If `true`, returns only entries with non-zero variance. Default: `false` | | `erp_vendor_ids` | String | No | Comma-separated ERP vendor IDs to filter variances by vendor | | `exception_type` | String | No | Filter by variance type: `"underbilling"` or `"overbilling"` | | `expand` | String | No | Use `expand=invoice_items` to include all invoice items inline (otherwise only most recent shown) | | `page` | Integer | No | Page number for pagination | | `limit` | Integer | No | Number of results per page | ### Response Fields | Field | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | Catalog entry ID | | `ottimate_company_id` | Company ID this catalog entry belongs to | | `item_name` | Item description from catalog | | `sku` | SKU code from the catalog entry | | `upc` | UPC code from the catalog entry | | `price` | Catalog pack price | | `unit_price` | Catalog unit price | | `pack_size` | Pack size configuration | | `case_size` | Pack size used for unit conversion | | `erp_vendor_name` | ERP-assigned vendor name | | `last_invoice_item` | Most recent invoice item with variance details (see below) | | `invoice_items` | All invoice items for this catalog entry (up to 10, with pagination metadata). Only included when `expand=invoice_items` is passed — otherwise only `last_invoice_item` is returned. | ### Last Invoice Item Object | Field | Description | | ----------------- | ------------------------------------------------------------ | | `id` | Invoice item ID | | `price` | Actual price charged on the invoice | | `invoice_date` | Date of the invoice | | `price_variance` | Difference between invoice price and effective catalog price | | `effective_price` | Catalog price adjusted for applicable allowances | --- ## Understanding Price Variance Price variance is calculated as: ``` price_variance = invoice_price - effective_price ``` Where `effective_price` is the catalog price adjusted for any applicable allowances. | Variance Value | Meaning | Example | | ------------------------ | ----------------------------------------------------------- | -------------------------------- | | Positive (e.g., `2.51`) | Overbilling - you were charged more than the catalog price | Invoice: $27.50, Catalog: $24.99 | | Negative (e.g., `-4.99`) | Underbilling - you were charged less than the catalog price | Invoice: $85.00, Catalog: $89.99 | | Zero or `null` | No variance - invoice matches catalog price | Invoice: $24.99, Catalog: $24.99 | --- ## Related Endpoints * [**Catalog Entries**](/catalog/catalog-entries) - Manage catalog entries and sync inventory data * [**Allowances**](/catalog/allowances) - Configure allowances that affect effective pricing * [**Invoices API**](/api-reference/api-reference/invoices/get-invoices-root) - Work with invoice data and matched catalog entries