Get batches
List batches, sorted oldest-first by creation date and filtered by the query parameters below. Only batches of batch-tracked products are returned; batches belonging to products on any other inventory-tracking method are never listed here.
Results are paginated. The response wraps the batches in data and returns a next_page URL; follow it to page through results, and stop when next_page is null.
By default each batch is returned without cost data. Pass include_costs=true to enrich every batch that currently holds positive on-hand quantity with its cost and quantity totals (total_cost_actual, total_cost_default, cost_per_unit_actual, cost_per_unit_default); batches with no on-hand stock omit those fields even when the flag is set. The single-batch GET /public/v1/batches/{id} endpoint always includes these totals, so use it when you need cost for one batch.
This endpoint returns eventually consistent data, with changes taking up to 1 second to propagate in responses.
Required permission: products_permissions_view. Results are additionally scoped to only the batches the authenticated user can access under their team restrictions, so two API keys at the same company may see different subsets.
Query parameters
Restrict the result to specific batches by ID (the same ID returned as each batch's id). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.
Return only batches belonging to any of these products (matches each batch's product_id). Repeat the bracketed key once per id; multiple ids are OR-ed.
Case-insensitive substring match on the batch's batch_number. batch_number is a user-set label and is not guaranteed unique, so this may return more than one batch.
Return only batches whose batch_number exactly matches (case-sensitive) any value in the list — send batch numbers exactly as they appear in responses. Repeat the bracketed key once per value.
Return only batches whose product is in any of these categories (matches the batch's product.category.id). Multiple ids are OR-ed.
Return only batches whose product is in any of these subcategories (matches the batch's product.subcategory.id). Multiple ids are OR-ed.
Return only batches whose product is in any of these groups (matches the batch's product.product_group.id). Multiple ids are OR-ed.
Return only batches whose product has any of these brands (matches the batch's product.brand.id). Multiple ids are OR-ed.
Return only batches whose product is supplied by any of these vendors (matches the batch's product.vendor.id; this is the company-relationship ID, not the raw company ID). Multiple ids are OR-ed.
Return only batches whose product has any of these strains (matches the batch's product.strain.id). Multiple ids are OR-ed.
Return only batches whose product carries any of these tags (matches an id in the batch's product.tags[].id). Multiple ids are OR-ed.
Return only batches whose product SKU exactly matches (case-insensitive) any value in the list (matches the batch's product.sku). Multiple values are OR-ed.
Keep only batches that currently hold active quantity (true) or none (false). Omit to match either.
Filter by batch creation time as a comma-separated ISO 8601 range start,end (inclusive). Omit either side to leave that bound open: 2022-07-10T00:00:00Z, matches on or after that instant, ,2022-07-10T00:00:00Z matches on or before it.
Restrict to batches owned by any of these Distru users (each batch's owner_id). Repeat the bracketed key once per ID; matches ANY. Unknown IDs match nothing; an empty list is no filter. At most 200 IDs.
Controls whether soft-deleted batches are included. no (the default) returns only non-deleted batches, only returns only soft-deleted batches, include returns both. SCREAMING_CASE is not used here — pass the lowercase value.
When true, each returned batch is enriched with its cost and on-hand quantity totals — total_cost_actual, total_cost_default, cost_per_unit_actual, and cost_per_unit_default. Defaults to false when omitted, in which case those four fields are left off the batch objects entirely (keeping the listing lighter). Even when true, the fields appear only for batches that currently hold positive on-hand quantity; a batch with no stock omits them. To always get cost for a single batch regardless of stock, use GET /public/v1/batches/{id}.
Page selector. Page size is fixed by the server; paginate by following the next_page URL in each response rather than building page selectors yourself — it is null on the last page. next_page uses page[after]=<cursor>, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.
Filter by the batch's most-recent modification time as a comma-separated ISO 8601 range start,end (inclusive). Omit either side to leave that bound open, e.g. ,2022-07-10T00:00:00Z matches batches last modified on or before that instant.
Filter by custom field values, as custom_data[{id}]=value where {id} is a custom field's numeric id. Repeat with different ids to filter on several fields at once; a record must match every one (AND). Matching is case-sensitive exact against the value stored on the record. The id must be a filterable custom field defined on this entity — use GET /public/v1/custom-fields?parent_object=batch to list the ids, their types, and which are filterable. A non-numeric id, an id not defined on this entity, or an id that isn't filterable returns a 400.
Response
A list of batches
Changes
No recorded changes to this endpoint across all 1 revision of this API.