> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockful.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost history

> Every recorded change to a variant's cost - purchase-order receipts and edits made in Shopify.

Every recorded change to a variant's cost - purchase-order receipts and edits made in Shopify.

## Example

```sql theme={null}
FROM cost_history
  SHOW cost_events, avg_event_cost
  GROUP BY product
  ORDER BY cost_events DESC
```

## Metrics

| Metric             | Type     | Description                                                                                          |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------- |
| `cost_events`      | Number   | Number of recorded cost changes.                                                                     |
| `avg_event_cost`   | Currency | Mean unit cost across the cost events in the range.                                                  |
| `min_event_cost`   | Currency | Lowest unit cost recorded in the range.                                                              |
| `max_event_cost`   | Currency | Highest unit cost recorded in the range.                                                             |
| `cost_swing`       | Currency | Highest minus lowest unit cost in the range - how much the price moved.                              |
| `cost_swing_pct`   | Percent  | Cost movement across the range as a % of the lowest cost recorded.                                   |
| `latest_avg_cost`  | Currency | Weighted-average landed cost after the most recent cost event in the range, summed across the group. |
| `net_units`        | Number   | Net units the cost events covered. Signed - receipt corrections write negative rows.                 |
| `first_event_date` | Date     | Earliest cost event in the range.                                                                    |
| `last_event_date`  | Date     | Most recent cost event in the range.                                                                 |

## Dimensions

| Dimension      | Description                                                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `product`      | Product with image, rendered as a single cell (variants roll up).                                                                                                                           |
| `sku`          | Variant SKU - splits a product-grain report into variant rows.                                                                                                                              |
| `variant`      | Variant title (e.g. "Small / Blue"), shown as a dash for products without options. Group by product too - on its own, variants sharing a title across different products fall into one row. |
| `vendor`       | Product brand, grouping under a blank value when unset.                                                                                                                                     |
| `product_type` | Product type, grouping under a blank value when unset.                                                                                                                                      |
| `source`       | What produced the cost event - a purchase-order receipt, or an edit made in Shopify.                                                                                                        |
| `event_date`   | The day the cost event was recorded.                                                                                                                                                        |

## Filters

| Filter                     | Type   | Description                                                                 |
| -------------------------- | ------ | --------------------------------------------------------------------------- |
| `collection`               | Number | Restrict to products in the selected collection(s).                         |
| `category`                 | Text   | Restrict to products in the selected category (matches sub-categories too). |
| `sales_channel`            | Number | Restrict to products published to the selected sales channel.               |
| `region_catalog`           | Number | Restrict to products in the selected region (market) catalog.               |
| `b2b_catalog`              | Number | Restrict to products in the selected B2B (market) catalog.                  |
| `company_location_catalog` | Number | Restrict to products in the selected company-location catalog.              |
| `product_title`            | Text   | Product title.                                                              |
| `sku`                      | Text   | Variant SKU.                                                                |
| `vendor`                   | Text   | Product brand.                                                              |
| `product_type`             | Text   | Product type.                                                               |
| `source`                   | Text   | What produced the cost event.                                               |
| `unit_cost_base`           | Number | The cost recorded by the event.                                             |

## Related datasets

* [Purchasing](/stockfulql/datasets/purchasing)
* [Purchase costs](/stockfulql/datasets/purchase_costs)
* [Goods receipts](/stockfulql/datasets/receipts)
* [Supplier performance](/stockfulql/datasets/supplier_performance)