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

# Inventory Analytics

> Retrieve comprehensive analytics and insights about your inventory performance

<Note>
  The Analytics API provides real-time insights into inventory performance, trends, and optimization opportunities.
</Note>

## Query Parameters

<ParamField query="metric_type" type="string" required>
  Type of analytics to retrieve:

  * `overview` - General inventory metrics
  * `turnover` - Inventory turnover analysis
  * `aging` - Stock aging report
  * `performance` - SKU performance metrics
  * `forecast_accuracy` - Forecast vs actual comparison
</ParamField>

<ParamField query="sku" type="string">
  Filter analytics for specific SKU
</ParamField>

<ParamField query="location_id" type="string">
  Filter by specific location
</ParamField>

<ParamField query="date_from" type="string">
  Start date for analytics period (ISO 8601)
</ParamField>

<ParamField query="date_to" type="string">
  End date for analytics period (ISO 8601)
</ParamField>

<ParamField query="group_by" type="string">
  Group results by: `sku`, `category`, `location`, `supplier`
</ParamField>

<ParamField query="include_trends" type="boolean">
  Include historical trend data. Default: false
</ParamField>

## Response

<ResponseField name="metric_type" type="string">
  Type of analytics returned
</ResponseField>

<ResponseField name="period" type="object">
  Analytics time period

  <Expandable title="properties">
    <ResponseField name="from" type="string">
      Start date (ISO 8601)
    </ResponseField>

    <ResponseField name="to" type="string">
      End date (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metrics" type="object">
  Core metrics based on metric\_type

  <Expandable title="properties">
    <ResponseField name="total_value" type="number">
      Total inventory value
    </ResponseField>

    <ResponseField name="total_units" type="integer">
      Total units in stock
    </ResponseField>

    <ResponseField name="unique_skus" type="integer">
      Number of unique SKUs
    </ResponseField>

    <ResponseField name="average_turnover" type="number">
      Average inventory turnover rate
    </ResponseField>

    <ResponseField name="stockout_rate" type="number">
      Percentage of SKUs out of stock
    </ResponseField>

    <ResponseField name="overstock_rate" type="number">
      Percentage of overstocked items
    </ResponseField>

    <ResponseField name="dead_stock_value" type="number">
      Value of non-moving inventory
    </ResponseField>

    <ResponseField name="carrying_cost" type="number">
      Total inventory carrying cost
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="breakdown" type="array">
  Detailed breakdown by grouping

  <Expandable title="properties">
    <ResponseField name="group" type="string">
      Group identifier (SKU, category, etc.)
    </ResponseField>

    <ResponseField name="name" type="string">
      Group name
    </ResponseField>

    <ResponseField name="metrics" type="object">
      Group-specific metrics

      <Expandable title="properties">
        <ResponseField name="units" type="integer">
          Units in stock
        </ResponseField>

        <ResponseField name="value" type="number">
          Inventory value
        </ResponseField>

        <ResponseField name="turnover_rate" type="number">
          Turnover rate
        </ResponseField>

        <ResponseField name="days_of_supply" type="number">
          Days of supply on hand
        </ResponseField>

        <ResponseField name="velocity" type="string">
          Movement velocity: `fast`, `medium`, `slow`, `non-moving`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="trends" type="object">
  Historical trend data (if requested)

  <Expandable title="properties">
    <ResponseField name="inventory_value" type="array">
      Time series of inventory values
    </ResponseField>

    <ResponseField name="turnover_rate" type="array">
      Time series of turnover rates
    </ResponseField>

    <ResponseField name="stockout_incidents" type="array">
      Historical stockout events
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="insights" type="array">
  AI-generated insights and recommendations

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Insight type: `opportunity`, `warning`, `recommendation`
    </ResponseField>

    <ResponseField name="severity" type="string">
      Severity level: `high`, `medium`, `low`
    </ResponseField>

    <ResponseField name="message" type="string">
      Insight description
    </ResponseField>

    <ResponseField name="affected_items" type="array">
      List of affected SKUs
    </ResponseField>

    <ResponseField name="potential_savings" type="number">
      Estimated savings if actioned
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.stateset.com/api/v1/inventory/analytics?metric_type=overview&include_trends=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const analytics = await stateset.inventory.analytics.get({
    metric_type: 'overview',
    date_from: '2024-01-01',
    date_to: '2024-11-15',
    include_trends: true
  });
  ```

  ```python Python theme={null}
  analytics = stateset.inventory.analytics.get(
      metric_type='overview',
      date_from='2024-01-01',
      date_to='2024-11-15',
      include_trends=True
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "metric_type": "overview",
    "period": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-11-15T23:59:59Z"
    },
    "metrics": {
      "total_value": 485750.00,
      "total_units": 12500,
      "unique_skus": 256,
      "average_turnover": 8.5,
      "stockout_rate": 0.03,
      "overstock_rate": 0.12,
      "dead_stock_value": 15000.00,
      "carrying_cost": 121437.50
    },
    "breakdown": [
      {
        "group": "Electronics",
        "name": "Electronics Category",
        "metrics": {
          "units": 3500,
          "value": 175000.00,
          "turnover_rate": 12.5,
          "days_of_supply": 29.2,
          "velocity": "fast"
        }
      },
      {
        "group": "Accessories",
        "name": "Accessories Category",
        "metrics": {
          "units": 5000,
          "value": 75000.00,
          "turnover_rate": 6.0,
          "days_of_supply": 60.8,
          "velocity": "medium"
        }
      }
    ],
    "trends": {
      "inventory_value": [
        { "date": "2024-01-01", "value": 450000 },
        { "date": "2024-02-01", "value": 465000 },
        { "date": "2024-03-01", "value": 478000 }
      ],
      "turnover_rate": [
        { "date": "2024-01-01", "rate": 7.5 },
        { "date": "2024-02-01", "rate": 8.0 },
        { "date": "2024-03-01", "rate": 8.5 }
      ]
    },
    "insights": [
      {
        "type": "opportunity",
        "severity": "high",
        "message": "15 SKUs have been non-moving for 180+ days",
        "affected_items": ["OLD-001", "OLD-002", "OLD-003"],
        "potential_savings": 15000.00
      },
      {
        "type": "warning",
        "severity": "medium",
        "message": "Electronics category showing 25% increase in stockouts",
        "affected_items": ["ELEC-101", "ELEC-102"],
        "potential_savings": 5000.00
      },
      {
        "type": "recommendation",
        "severity": "low",
        "message": "Consider implementing ABC classification for better control",
        "affected_items": [],
        "potential_savings": 8000.00
      }
    ]
  }
  ```
</ResponseExample>

## Metric Types

### Overview Analytics

General inventory health metrics and KPIs.

```javascript theme={null}
const overview = await stateset.inventory.analytics.get({
  metric_type: 'overview',
  group_by: 'category'
});
```

### Turnover Analysis

Detailed inventory turnover rates and velocity metrics.

```javascript theme={null}
const turnover = await stateset.inventory.analytics.get({
  metric_type: 'turnover',
  group_by: 'sku',
  date_from: '2024-01-01'
});
```

### Aging Report

Analysis of stock age and identification of slow-moving items.

```javascript theme={null}
const aging = await stateset.inventory.analytics.get({
  metric_type: 'aging',
  location_id: 'loc_warehouse_001'
});
```

### Performance Metrics

SKU-level performance including sales velocity and profitability.

```javascript theme={null}
const performance = await stateset.inventory.analytics.get({
  metric_type: 'performance',
  sku: 'WIDGET-001',
  include_trends: true
});
```

### Forecast Accuracy

Compare forecasted demand with actual sales to improve planning.

```javascript theme={null}
const accuracy = await stateset.inventory.analytics.get({
  metric_type: 'forecast_accuracy',
  date_from: '2024-06-01',
  date_to: '2024-11-01'
});
```

## Exporting Analytics

Export analytics data in various formats:

```javascript theme={null}
// Export as CSV
const csvExport = await stateset.inventory.analytics.export({
  metric_type: 'overview',
  format: 'csv'
});

// Export as PDF report
const pdfReport = await stateset.inventory.analytics.export({
  metric_type: 'performance',
  format: 'pdf',
  include_charts: true
});
```

## Scheduling Reports

Set up automated analytics reports:

```javascript theme={null}
const schedule = await stateset.inventory.analytics.schedule({
  name: 'Weekly Inventory Report',
  metric_type: 'overview',
  frequency: 'weekly',
  recipients: ['ops@company.com'],
  format: 'pdf'
});
```

## Related Endpoints

* [Inventory Planning](/api-reference/inventory/planning) - Generate inventory plans
* [List Inventory](/api-reference/inventory/get) - View current inventory
* [Inventory Webhooks](/api-reference/webhooks/inventory) - Real-time inventory events