# Stock levels

Stock batches ordered from your farm, and reporting the units you have printed.

## Endpoints

-   [GET `/v1/print-farm/stock-levels`](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#listPrintFarmStockLevels)
-   [GET `/v1/print-farm/stock-levels/{id}`](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#getPrintFarmStockLevel)
-   [PATCH `/v1/print-farm/stock-levels/{id}/items-made`](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#addPrintFarmStockLevelItemsMade)

## The stock level object

### Attributes

-   `id` (string): Opaque public identifier for this stock-level row (`slv_` prefix + 33 base62 chars). Use this value verbatim when referencing the row in other endpoints.
-   `stock_id` (string): Public identifier of the parent stock (`stk_…`).
-   `stock_items_left` (number): Number of products remaining in this stock level.
-   `quantity` (number): Number of stocks bought (`quantity_purchased`). E.g. 4 means 4 stock-level rows were created.
-   `created_at` (timestamp): ISO 8601 timestamp of when this stock level was created.
-   `status` (string): Lifecycle status of the stock level.
    
    Possible values: `pending`, `in_production`, `completed`, `consumed`.
    
-   `stock_items_purchased` (number): Total number of products bought across this stock level. If `quantity = 4` and each stock holds 12 items, `stock_items_purchased = 48`.
-   `order_id` (object, optional): Identifier of the order this stock level was created for. Null for proactive stock.
-   `items_made` (number): Number of products produced so far.
-   `items_consumed` (number): Number of products consumed/shipped so far.

**The stock level object**

```json
{
  "id": "slv_hG5dC2vKrPm8nT3sJ6yF1xL9bQ4wA7uZdF",
  "stock_id": "stk_fL3sB8eYzKnQ7mX2dC9vR4tH6jW1uPbAcN",
  "stock_items_left": 11,
  "quantity": 4,
  "created_at": "2026-03-24T12:00:00.000Z",
  "status": "pending",
  "stock_items_purchased": 48,
  "order_id": "ORD-001",
  "items_made": 0,
  "items_consumed": 0
}
```

## List stock levels at your print farm

GET `/v1/print-farm/stock-levels`

- **Credentials**: An API key with the `READ_STOCK` or `FULL` permission.

- **For**: Print farms

- **Operation id**: `listPrintFarmStockLevels`

Returns a paginated list of stock-level rows belonging to your print farm, sorted by creation date (newest first). Filter by `status`, `stock_id`, or `order_id`. Requires an API key with the `READ_STOCK` (or `FULL`) permission scope.

### Query parameters

-   `page` (integer): 1-based page index.
    
    Range at least 1. Defaults to 1.
    
-   `page_size` (integer): Page size (max 100).
    
    Range 1 to 100. Defaults to 20.
    
-   `status` (string): Filter by status. Accepts a comma-separated list (pending, in\_production, completed, consumed).
-   `stock_id` (string): Filter by parent stock public id (`stk_…`). Unknown or wrong-type values return an empty result rather than an error.
-   `order_id` (string): Filter by order id (exact match).

### Returns 200 OK

Paginated list of stock levels belonging to the authenticated print farm.

Response attributes (ListPrintFarmStockLevelsResponseDto):

-   `stock_levels` (array of PrintFarmStockLevelResponseDto): Stock levels on this page, sorted by creation date (newest first).
    
    Described in [the stock level object](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#farm_stock_level_object).
    
-   `page` (number): Page number returned, matching the `page` query parameter.
    
    Range at least 1.
    
-   `page_size` (number): Number of items per page, matching the `page_size` query parameter.
    
    Range 1 to 100.
    
-   `total` (number): Total number of stock levels across all pages (after filters are applied).
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of stock levels belonging to the authenticated print farm.
-   `400`: `page` or `page_size` is outside the allowed range.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the print farm error body](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/stock-levels" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "stock_levels": [
    {
      "id": "slv_hG5dC2vKrPm8nT3sJ6yF1xL9bQ4wA7uZdF",
      "stock_id": "stk_fL3sB8eYzKnQ7mX2dC9vR4tH6jW1uPbAcN",
      "stock_items_left": 11,
      "quantity": 4,
      "created_at": "2026-03-24T12:00:00.000Z",
      "status": "pending",
      "stock_items_purchased": 48,
      "order_id": "ORD-001",
      "items_made": 0,
      "items_consumed": 0
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42
}
```

## Get one stock level at your print farm

GET `/v1/print-farm/stock-levels/{id}`

- **Credentials**: An API key with the `READ_STOCK` or `FULL` permission.

- **For**: Print farms

- **Operation id**: `getPrintFarmStockLevel`

Returns a single stock-level row by id, scoped to your print farm. Requires an API key with the `READ_STOCK` (or `FULL`) permission scope.

### Path parameters

-   `id` (string, required): The public stock-level identifier (`slv_…`) returned by the list endpoint.

### Returns 200 OK

The requested stock level. Returns [the stock level object](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#farm_stock_level_object).

### Responses

-   `200`: The requested stock level.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `404`: No stock level with this `id` is allocated to your print farm.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the print farm error body](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/stock-levels/slv_hG5dC2vKrPm8nT3sJ6yF1xL9bQ4wA7uZdF" \
  -H "x-api-key: $DAPI_API_KEY"
```

## Add items printed to a stock level

PATCH `/v1/print-farm/stock-levels/{id}/items-made`

- **Credentials**: An API key with the `WRITE_STOCK` or `FULL` permission.

- **For**: Print farms

- **Operation id**: `addPrintFarmStockLevelItemsMade`

Increments `items_made` on a specific stock-level row by the given `quantity`. Transitions `pending → in_production` on the first non-zero increment, and `in_production → completed` when `items_made` reaches `stock_items_purchased` - completion also credits the farm wallet (one `payments` row, one `wallet.balance` bump) using `stock_level.manufacturer_price` as the payout amount.

Pass an `Idempotency-Key` header (any opaque string up to 255 chars) to make retries safe: a second request with the same key + body returns the cached response without re-executing. Same key with a different body returns `422`; an in-flight retry returns `409`.

Requires an API key with the `WRITE_STOCK` (or `FULL`) permission scope.

### Path parameters

-   `id` (string, required): The public stock-level identifier (`slv_…`).

### Headers

-   `Idempotency-Key` (string): Opaque caller-generated key (UUID recommended). When present, identical requests with the same key + body return the cached prior response without re-executing. Up to 255 characters.

### Request body

Quantity to add to `items_made` for this stock level.

-   `quantity` (number, required): Number of items to add to this stock level's `items_made` count. Must be ≥ 1 and must not push the total above `stock_items_purchased`.
    
    Range 1 to 100000.
    

### Returns 200 OK

The updated stock-level row. Returns [the stock level object](https://public-api.dapi.digital/docs/reference/print-farm-stock-levels.md#farm_stock_level_object).

### Responses

-   `200`: The updated stock-level row.
-   `400`: Body validation failed, or the requested `quantity` would push `items_made` past `stock_items_purchased`.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `404`: No stock level with this `id` is allocated to your print farm.
-   `409`: The stock level is `consumed`, was modified concurrently, or another request with the same `Idempotency-Key` is already in flight.
-   `422`: `Idempotency-Key` reuse with a different request body, or the key exceeded the maximum length (255 chars).
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the print farm error body](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl -X PATCH "https://public-api.dapi.digital/v1/print-farm/stock-levels/slv_hG5dC2vKrPm8nT3sJ6yF1xL9bQ4wA7uZdF/items-made" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1
}'
```

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/reference/print-farm-stock-levels. Index of every page: https://public-api.dapi.digital/docs/llms.txt.
