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 - Get invoice items and purchase history for a specific catalog item
2. 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

1
GET /v1/catalog/variances/{id}/invoice-items

Example Request

1
GET /v1/catalog/variances/cte_12345/invoice-items?page=1&limit=20

Response

1
{
2
  "count": 5,
3
  "results": [
4
    {
5
      "id": 98765,
6
      "invoice_id": 54321,
7
      "item_name": "Roma Tomatoes 6CT",
8
      "price": 27.5,
9
      "quantity": 10,
10
      "invoice_date": "2024-12-01",
11
      "price_variance": 2.51,
12
      "effective_price": 24.99
13
    },
14
    {
15
      "id": 98760,
16
      "invoice_id": 54310,
17
      "item_name": "Roma Tomatoes 6CT",
18
      "price": 26.99,
19
      "quantity": 12,
20
      "invoice_date": "2024-11-15",
21
      "price_variance": 2.0,
22
      "effective_price": 24.99
23
    }
24
  ]
25
}

Path Parameters

Query Parameters

Invoice Item Fields

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

1
GET /v1/catalog/variances

Example Request

1
GET /v1/catalog/variances?ottimate_company_id=15196&variance_only=true&page=1&limit=20

Response

1
{
2
  "count": 15,
3
  "results": [
4
    {
5
      "id": "12345",
6
      "ottimate_company_id": 15196,
7
      "item_name": "Roma Tomatoes 6CT",
8
      "price": 27.0,
9
      "unit_price": 4.5,
10
      "pack_size": "6 CT",
11
      "case_size": "6 CT",
12
      "erp_vendor_name": "Sysco Foods",
13
      "last_invoice_item": {
14
        "id": 98765,
15
        "price": 27.5,
16
        "invoice_date": "2024-12-01",
17
        "price_variance": 2.51,
18
        "effective_price": 24.99
19
      }
20
    },
21
    {
22
      "id": "12346",
23
      "ottimate_company_id": 15196,
24
      "item_name": "Chicken Breast 10lb Case",
25
      "price": 90.0,
26
      "unit_price": 8.99,
27
      "pack_size": "10 LB",
28
      "case_size": "10 LB",
29
      "erp_vendor_name": "US Foods",
30
      "last_invoice_item": {
31
        "id": 98766,
32
        "price": 85.0,
33
        "invoice_date": "2024-11-28",
34
        "price_variance": -4.99,
35
        "effective_price": 89.99
36
      }
37
    }
38
  ]
39
}

Query Parameters

Response Fields

Last Invoice Item Object

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.

Related Endpoints

• Catalog Entries - Manage catalog entries and sync inventory data
• Allowances - Configure allowances that affect effective pricing
• Invoices API - Work with invoice data and matched catalog entries