Stock Levels

scope: inventory

Read-only endpoints that return aggregated stock quantities. The product breakdown shows total units per product across all warehouses. The carton breakdown shows individual carton types with stock counts per warehouse, including physical dimensions and weight.

Which endpoint do I need?

Product Breakdown

Total units per product, summed across all carton types and warehouses.

Best for: e-commerce stock sync, availability checks, reorder alerts.

Carton Breakdown

Stock counts per carton type per warehouse, with dimensions & weight.

Best for: SPD shipment planning, warehouse ops, packaging logistics.

Endpoints

GET

/v0/inventory/products/breakdown

Stock levels aggregated by product

GET

/v0/inventory/cartons/breakdown

Stock levels aggregated by carton type, broken down per warehouse

Product Breakdown

Returns each product with total unit counts summed across all carton types and all warehouses. Use this to get a high-level view of how much stock you have for each product.

Query Parameters

Parameter	Type	Description
`updatedSince`	ISO 8601	Only return items updated after this timestamp. Useful for incremental syncing.
`includeDeleted`	boolean	Include soft-deleted products in the response (default: false)
`skip`	number	Number of records to skip (default: 0)
`take`	number	Number of records to return (default: 10, max: 50)

curl

curl "https://api.3plguys.com/v0/inventory/products/breakdown?take=50" \
  -H "Authorization: Bearer <token>"

Node.js

const res = await fetch(
  "https://api.3plguys.com/v0/inventory/products/breakdown?take=50",
  { headers: { Authorization: `Bearer ${token}` } }
);
const levels = await res.json();

Python

res = httpx.get(
    "https://api.3plguys.com/v0/inventory/products/breakdown",
    params={"take": 50},
    headers={"Authorization": f"Bearer {token}"},
)
levels = res.json()

Response

[
  {
    "id": "1",
    "name": "Egg Shells",
    "sku": "ABC123",
    "quantity": 290,
    "warehouses": [
      { "id": "1", "name": "Main Warehouse", "quantity": 290 }
    ],
    "createdAt": "2025-01-15T08:30:00.000Z",
    "updatedAt": "2025-02-20T14:00:00.000Z",
    "deletedAt": null
  }
]

Response Fields

Parameter	Type	Description
`id`*	string	Product ID
`name`*	string	Product name
`sku`*	string	Product SKU
`quantity`*	number	Total units across all warehouses (sum of all carton types × units per carton)
`warehouses`*	array	Unit count broken down by warehouse
`warehouses[].id`*	string	Warehouse ID
`warehouses[].name`*	string	Warehouse name
`warehouses[].quantity`*	number	Total units at this warehouse
`createdAt`*	ISO 8601	When the product was created
`updatedAt`*	ISO 8601	Last update timestamp (includes stock changes)
`deletedAt`	ISO 8601 \| null	Timestamp when the product was soft-deleted, null if active. Deleted products report 0 quantity.

Carton Breakdown

Returns each carton type with stock counts per warehouse, the products it contains, and its physical dimensions and weight. Dimensions are normalized to millimeters and weight to grams.

Query Parameters

Parameter	Type	Description
`updatedSince`	ISO 8601	Only return items updated after this timestamp. Useful for incremental syncing.
`includeDeleted`	boolean	Include soft-deleted carton types in the response (default: false)
`skip`	number	Number of records to skip (default: 0)
`take`	number	Number of records to return (default: 10, max: 50)

curl

curl "https://api.3plguys.com/v0/inventory/cartons/breakdown?take=50" \
  -H "Authorization: Bearer <token>"

Node.js

const res = await fetch(
  "https://api.3plguys.com/v0/inventory/cartons/breakdown?take=50",
  { headers: { Authorization: `Bearer ${token}` } }
);
const cartonLevels = await res.json();

Response

[
  {
    "id": "1",
    "name": "Egg Shells [10-Pack Case]",
    "contents": [
      {
        "id": "1",
        "sku": "ABC123",
        "name": "Egg Shells",
        "quantity": 10,
        "createdAt": "2025-01-15T08:30:00.000Z",
        "updatedAt": "2025-02-20T14:00:00.000Z"
      }
    ],
    "quantity": 50,
    "warehouses": [
      { "id": "1", "name": "Main Warehouse", "quantity": 50 }
    ],
    "dimensions": { "length": 305, "width": 254, "height": 203 },
    "weight": 2268,
    "createdAt": "2025-01-15T08:30:00.000Z",
    "updatedAt": "2025-02-20T14:00:00.000Z",
    "deletedAt": null
  }
]

Response Fields

Parameter	Type	Description
`id`*	string	Carton type ID
`name`*	string	Formatted as "Product Name [Carton Name]"
`contents`*	array	Products contained in this carton type
`contents[].id`*	string	Product ID
`contents[].sku`*	string	Product SKU
`contents[].name`*	string	Product name
`contents[].quantity`*	number	Units of this product per carton
`contents[].createdAt`*	ISO 8601	When the product was created
`contents[].updatedAt`*	ISO 8601	Last update timestamp of the product
`quantity`*	number	Total carton count across all warehouses
`warehouses`*	array	Carton count broken down by warehouse
`warehouses[].id`*	string	Warehouse ID
`warehouses[].name`*	string	Warehouse name
`warehouses[].quantity`*	number	Number of cartons at this warehouse
`dimensions`*	object	Physical dimensions in millimeters
`dimensions.length`*	number	Length in mm
`dimensions.width`*	number	Width in mm
`dimensions.height`*	number	Height in mm
`weight`*	number	Weight in grams
`createdAt`*	ISO 8601	When the carton type was created
`updatedAt`*	ISO 8601	Last update timestamp (includes stock changes)
`deletedAt`	ISO 8601 \| null	Timestamp when the carton type was soft-deleted, null if active. Deleted cartons report 0 quantity.

Units are normalized

Dimensions are always returned in millimeters, regardless of how they were entered (inches are converted automatically).
Weight is always returned in grams (pounds are converted automatically).
Use the updatedSince parameter for efficient polling — only fetch what changed since your last sync.

Cartons

Warehouses