# Stocks

Ready-made stock products with at least one batch at your farm.

## Endpoints

-   [GET `/v1/print-farm/stocks`](https://public-api.dapi.digital/docs/reference/print-farm-stocks.md#listPrintFarmStocks)
-   [GET `/v1/print-farm/stocks/{id}`](https://public-api.dapi.digital/docs/reference/print-farm-stocks.md#getPrintFarmStock)

## The stock object

### Attributes

-   `id` (string): Opaque public identifier for this stock (`stk_` prefix + 33 base62 chars).
-   `name` (string): Display name of the stock.
-   `description` (object, optional): Free-text description of the stock.
-   `stock_items_number` (number): Total number of stock items in this stock as defined by the designer.
-   `sales_price` (object, optional): Authoritative aggregate sales price for the stock (designer-set, admin-approved).
-   `approval_status` (string): Approval lifecycle status (e.g. pending, approved, rejected).
-   `design_list` (array of PrintFarmStockDesignRefDto): Designs included in this stock.
    -   `design_id` (string): Public identifier of the design (`dsg_…`).
    -   `count` (number): Number of copies of this design included per stock unit.
-   `region_config` (array of PrintFarmStockRegionConfigDto): Per-region configuration. Each entry exposes the manufacturer price for the region.
    -   `region_id` (string): Opaque public identifier of the print-farm region (`reg_…`). Encode-only - no endpoint currently consumes this id.
    -   `price` (object, optional): Manufacturer price for this stock in the given region. Authoritative per-region manufacturer price (the top-level `manufacturer_price` is deprecated).
-   `extra_parts_config` (object, optional): Free-form extra parts configuration as stored on the stock.
-   `created_at` (timestamp): ISO 8601 timestamp of when this stock was created.
-   `updated_at` (timestamp): ISO 8601 timestamp of when this stock was last updated.
-   `approved_at` (object, optional): ISO 8601 timestamp of when this stock was approved. Null when not yet approved.

**The stock object**

```json
{
  "id": "stk_fL3sB8eYzKnQ7mX2dC9vR4tH6jW1uPbAcN",
  "name": "Dragon Figurine Stock",
  "description": "Pre-printed dragon figurines, batch of 48.",
  "stock_items_number": 48,
  "sales_price": "20.00",
  "approval_status": "approved",
  "design_list": [
    {
      "design_id": "dsg_kP4xT8aBnLf2sH9eY3jZ5dM7cR1vQbWtJ",
      "count": 1
    }
  ],
  "region_config": [
    {
      "region_id": "reg_dF8kP3xL6sV2nH9mT5cR1jY4bQ7wA9uZeM",
      "price": "12.50"
    }
  ],
  "extra_parts_config": {},
  "created_at": "2026-03-24T12:00:00.000Z",
  "updated_at": "2026-04-02T15:30:00.000Z",
  "approved_at": "2026-03-25T08:30:00.000Z"
}
```

## List stocks visible to your print farm

GET `/v1/print-farm/stocks`

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

- **For**: Print farms

- **Operation id**: `listPrintFarmStocks`

Returns a paginated list of stocks that have at least one `stock_level` row at one of your farms, sorted by creation date (newest first). Filter by `id`, `name`, or `approval_status`. 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.
    
-   `id` (array of string): Filter by stock id. Accepts a comma-separated list of UUIDs.
-   `name` (string): Filter by stock name (case-insensitive partial match).
-   `approval_status` (string): Filter by approval status. Accepts a comma-separated list (e.g. `approved,pending`).

### Returns 200 OK

Paginated list of stocks visible to the authenticated print farm.

Response attributes (ListPrintFarmStocksResponseDto):

-   `stocks` (array of PrintFarmStockResponseDto): Stocks on this page, sorted by creation date (newest first).
    
    Described in [the stock object](https://public-api.dapi.digital/docs/reference/print-farm-stocks.md#farm_stock_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 stocks across all pages (after filters are applied).
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of stocks visible 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/stocks" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "stocks": [
    {
      "id": "stk_fL3sB8eYzKnQ7mX2dC9vR4tH6jW1uPbAcN",
      "name": "Dragon Figurine Stock",
      "description": "Pre-printed dragon figurines, batch of 48.",
      "stock_items_number": 48,
      "sales_price": "20.00",
      "approval_status": "approved",
      "design_list": [
        {
          "design_id": "dsg_kP4xT8aBnLf2sH9eY3jZ5dM7cR1vQbWtJ",
          "count": 1
        }
      ],
      "region_config": [
        {
          "region_id": "reg_dF8kP3xL6sV2nH9mT5cR1jY4bQ7wA9uZeM",
          "price": "12.50"
        }
      ],
      "extra_parts_config": {},
      "created_at": "2026-03-24T12:00:00.000Z",
      "updated_at": "2026-04-02T15:30:00.000Z",
      "approved_at": "2026-03-25T08:30:00.000Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42
}
```

## Get one stock visible to your print farm

GET `/v1/print-farm/stocks/{id}`

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

- **For**: Print farms

- **Operation id**: `getPrintFarmStock`

Returns a single stock by id, scoped to stocks that have a `stock_level` row at one of your farms. Requires an API key with the `READ_STOCK` (or `FULL`) permission scope.

### Path parameters

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

### Returns 200 OK

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

### Responses

-   `200`: The requested stock.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have the required permission scope.
-   `404`: No stock with this `id` has any stock\_level at your print farms.
-   `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/stocks/stk_fL3sB8eYzKnQ7mX2dC9vR4tH6jW1uPbAcN" \
  -H "x-api-key: $DAPI_API_KEY"
```

---

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