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

# Get Fulfillment Stats

> Get headline fulfillment performance statistics

<Note>
  **V2 Preview** — This endpoint is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

Returns headline fulfillment performance metrics: average days to fulfill, count of orders unfulfilled for 7+ days, and the percentage of orders fulfilled on time (within 7 days). Vendor tokens are automatically scoped to your own items.

### Use Cases

* Display fulfillment performance KPIs on your vendor dashboard
* Track whether your fulfillment speed is improving over time
* Identify if you have a backlog of overdue orders

### Required Scope

`fulfillments:read`

## Query Parameters

<ParamField query="startDate" type="string">
  ISO 8601 lower bound on the date filter. Example: `2026-01-01T00:00:00Z`.
</ParamField>

<ParamField query="endDate" type="string">
  ISO 8601 upper bound on the date filter.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "stats": {
      "averageDaysToFulfill": 2.3,
      "unfulfilledFor7Days": 4,
      "fulfilledOnTimePercentage": 92.5
    }
  }
}
```

### Response Fields

| Field                       | Type   | Description                                                                        |
| --------------------------- | ------ | ---------------------------------------------------------------------------------- |
| `averageDaysToFulfill`      | number | The average number of days between order creation and fulfillment.                 |
| `unfulfilledFor7Days`       | number | Count of orders that have been unfulfilled for 7 or more days (anchored to today). |
| `fulfilledOnTimePercentage` | number | Percentage of orders fulfilled within 7 days of creation.                          |

## Example

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/fulfillments/stats?startDate=2026-04-01T00:00:00Z&endDate=2026-05-19T23:59:59Z" \
  -H "x-access-token: YOUR_VENDOR_JWT"
```