Stock levels

View as Markdown

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

The stock level object

Attributes

  • idstring

    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_idstring

    Public identifier of the parent stock (stk_…).

  • stock_items_leftnumber

    Number of products remaining in this stock level.

  • quantitynumber

    Number of stocks bought (quantity_purchased). E.g. 4 means 4 stock-level rows were created.

  • created_attimestamp

    ISO 8601 timestamp of when this stock level was created.

  • statusstring

    Lifecycle status of the stock level.

    Possible valuespendingin_productioncompletedconsumed
  • stock_items_purchasednumber

    Total number of products bought across this stock level. If quantity = 4 and each stock holds 12 items, stock_items_purchased = 48.

  • order_idobjectOptional

    Identifier of the order this stock level was created for. Null for proactive stock.

  • items_madenumber

    Number of products produced so far.

  • items_consumednumber

    Number of products consumed/shipped so far.

The stock level object
{
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  
}

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

  • pageinteger

    1-based page index.

    Range at least 1. Defaults to 1.
  • page_sizeinteger

    Page size (max 100).

    Range 1 to 100. Defaults to 20.
  • statusstring

    Filter by status. Accepts a comma-separated list (pending, in_production, completed, consumed).

  • stock_idstring

    Filter by parent stock public id (stk_…). Unknown or wrong-type values return an empty result rather than an error.

  • order_idstring

    Filter by order id (exact match).

Returns200 OK

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

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.

GET/v1/print-farm/stock-levels
curl "https://public-api.dapi.digital/v1/print-farm/stock-levels" \
  -H "x-api-key: $DAPI_API_KEY"
Response
{
  "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

  • idstringRequired

    The public stock-level identifier (slv_…) returned by the list endpoint.

Returns200 OK

The requested stock level. Returns the 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.

GET/v1/print-farm/stock-levels/{id}
curl "https://public-api.dapi.digital/v1/print-farm/stock-levels/slv_hG5dC2vKrPm8nT3sJ6yF1xL9bQ4wA7uZdF" \
  -H "x-api-key: $DAPI_API_KEY"
Response
{
  "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
}

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

  • idstringRequired

    The public stock-level identifier (slv_…).

Headers

  • Idempotency-Keystring

    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.

  • quantitynumberRequired

    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.

Returns200 OK

The updated stock-level row. Returns the 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.

PATCH/v1/print-farm/stock-levels/{id}/items-made
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
}'
Response
{
  "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
}