Search packages | Distru Documentation

Searches inventory packages — the physical containers stock is held in, each carrying its compliance tag where the product is package-tracked.

Inputs

Every tool also takes the common inputs.

Field	Type	Required	Description
limit	integer	No	Default: `10`
cursor	string	No	nextCursor of the previous call; keep the other arguments unchanged.
ids	string[]	No	Package IDs.
licenseIds	string[]	No	Resolve via distru-search-licenses.
locationIds	string[]	No	Resolve via distru-search-locations.
productIds	string[]	No	Resolve via distru-search-products.
productCategoryIds	string[]	No	Product category of the packages. ORed with productSubcategoryIds; a listed subcategory of a listed category narrows that category to it. Resolve via distru-search-lookups (type PRODUCT_CATEGORY).
productSubcategoryIds	string[]	No	Product subcategory of the packages. See productCategoryIds. Resolve via distru-search-lookups (type PRODUCT_CATEGORY, each row's subcategories).
productTagIds	string[]	No	Any of these tags on the product. Resolve via distru-search-lookups (type PRODUCT_TAG).
vendorIds	string[]	No	The vendor set on the product, not the company an order was placed with. Resolve via distru-search-companies.
brandIds	string[]	No	Product brand of the packages, itself a company. Resolve via distru-search-companies, or read it on a distru-search-products row.
productGroupIds	string[]	No	Resolve via distru-search-lookups (type PRODUCT_GROUP).
search	string	No	Case-insensitive substring of Metrc label or product name/SKU, plus fuzzy match on product name. A full-length Metrc label is looked up exactly. Ranks label matches first, then by product-name similarity; sortBy ignored.
status	enum `ACTIVEANYINACTIVE`	No	Default ACTIVE, or ANY when ids is set. INACTIVE = hidden in Distru via distru-bulk-update-packages isActive; still active in Metrc.
distruStatuses	enum[] `ACTIVEASSEMBLINGDESTROYEDDISCONTINUEDFINISHEDON_HOLDRETURNINGSELLINGSOLDTRANSFERRED`	No	ACTIVE = sellable on-hand; ASSEMBLING, SELLING, RETURNING = committed to work in progress; DESTROYED, FINISHED, SOLD, TRANSFERRED, DISCONTINUED = gone. SOLD and TRANSFERRED keep the quantity they left with, so they match withQuantity true, not false.
withQuantity	boolean	No	Has quantity > 0, whatever its Distru status; false = quantity 0 (emptied by use, not SOLD or TRANSFERRED, which keep their last quantity). Default true, except no quantity filter when ids is set or search looks like a full compliance tag (16+ letters/digits, no spaces).
isTestSample	boolean	No	true: only lab test sample packages; false: excludes them.
hasTestResult	boolean	No	true: packages with a test result, primary or not, own or inherited; false: packages with none.
labTestingStates	enum[] `FAILEDNOT_TESTEDPASSEDPENDING`	No	PASSED = test or retest passed; FAILED = test or retest failed; NOT_TESTED = not sampled or testing not required, and every package not tracked in Metrc; PENDING = anything else: sampled and awaiting results, remediated and awaiting a retest, or only R&D tests done.
isFinishedGood	boolean	No	Metrc's finished-good flag. Packages on licenses that can't set it are left out either way.
syncing	boolean	No	Has a change still being sent to Metrc. For why, use distru-get-package.
customFields	object[]	No	Set one of contains, anyOf or onOrAfter/onOrBefore per entry. Records with no value for the field never match.
customFields[].customFieldId	string	Yes	Resolve via distru-search-custom-fields.
customFields[].contains	string	No	TEXT: case-insensitive substring.
customFields[].anyOf	string[]	No	DROPDOWN, CHECKBOX: any of these options, case-sensitive.
customFields[].onOrAfter	string	No	DATE: YYYY-MM-DD, company timezone.
customFields[].onOrBefore	string	No	DATE: YYYY-MM-DD, company timezone.
thcPercentageTotal	object	No	Filter packages by primaryTestResult.thcPercentageTotal, the total THC percentage on their primary test result, e.g. {min: 28} for 28% and up. Records without a primary test result, or whose total THC is not recorded, never match.
thcPercentageTotal.min	string or number	No	Lowest total THC percentage to keep, inclusive.
thcPercentageTotal.max	string or number	No	Highest total THC percentage to keep, inclusive.
sortBy	object	No	Default: most recently updated first. Ignored when search is set.
sortBy.direction	enum `ASCDESC`	Yes
sortBy.field	enum `BATCH_NUMBERCOMPLIANCE_LABELEXPIRATION_DATEINSERTED_ATQUANTITYUPDATED_AT`	Yes	BATCH_NUMBER = the package's own grouping label, not the linked Distru batch. BATCH_NUMBER and EXPIRATION_DATE put packages without one last, both directions.

Output

Presence on a nested field assumes its parent exists.

Field	Type	Presence
hasMore	boolean	Always
nextCursor	string	Can be absent
totalCount	integer	Can be absent
items	object[]	Always
items[].id	string	Always
items[].customFields	object[]	Always
items[].customFields[].customField	object	Always
items[].customFields[].customField.id	string	Always
items[].customFields[].customField.name	string	Always
items[].customFields[].customField.fieldType	enum `CHECKBOXDATEDROPDOWNTEXT`	Always
items[].customFields[].value	string	Can be null
items[].metrcLabel	string	Always
items[].complianceType	enum `BIOTRACKMETRCNONE`	Always
items[].metrcId	number	Can be null
items[].complianceProductName	string	Can be null
items[].complianceStrainName	string	Can be null
items[].distruStatus	enum `ACTIVEASSEMBLINGDESTROYEDDISCONTINUEDFINISHEDON_HOLDRETURNINGSELLINGSOLDTRANSFERRED`	Always
items[].isActive	boolean	Always
items[].syncing	boolean	Always
items[].batchNumber	string	Can be null
items[].compliancePackagedDate	string	Can be null
items[].harvestDate	string	Can be null
items[].expirationDate	string	Can be null
items[].finishedAt	string	Can be null
items[].insertedAt	string	Always
items[].updatedAt	string	Always
items[].isTestSample	boolean	Always
items[].isTradeSample	boolean	Always
items[].isFinishedGood	boolean	Can be null
items[].labTestingState	enum `FAILEDNOT_TESTEDPASSEDPENDING`	Always
items[].labTestingStateDate	string	Can be null
items[].quantity	string	Always
items[].quantityActive	string	Always
items[].quantityAssembling	string	Always
items[].quantityInMetrc	string	Can be null
items[].quantityCost	string	Can be null
items[].unitType	object	Always
items[].unitType.id	string	Always
items[].unitType.name	string	Always
items[].product	object	Always
items[].product.id	string	Always
items[].product.name	string	Always
items[].product.sku	string	Always
items[].batch	object	Always
items[].batch.id	string	Always
items[].batch.name	string	Always
items[].location	object	Always
items[].location.id	string	Always
items[].location.name	string	Always
items[].license	object	Always
items[].license.id	string	Always
items[].license.licenseNumber	string	Always
items[].activeSalesOrder	object	Can be null
items[].activeSalesOrder.id	string	Always
items[].activeSalesOrder.orderNumber	string	Always
items[].primaryTestResult	object	Can be null
items[].primaryTestResult.id	string	Always
items[].primaryTestResult.name	string	Always
items[].primaryTestResult.labName	string	Can be null
items[].primaryTestResult.releaseDate	string	Can be null
items[].primaryTestResult.thcPercentage	string	Can be null
items[].primaryTestResult.thcPercentageTotal	string	Can be null
items[].primaryTestResult.cbdPercentage	string	Can be null
items[].primaryTestResult.cbdPercentageTotal	string	Can be null

What the AI reads

Searches inventory packages — the physical containers stock is held in, each carrying its compliance tag where the product is package-tracked. One row per package with its compliance identity, Distru status, lab testing and potency, quantities and quantity cost, and the product, batch, location and license it belongs to. primaryTestResult includes results inherited from the packages it was made from, so skip distru-search-test-results for those. isFinishedGood is Metrc's finished-good flag, null where the package's license can't set it. Use it to resolve a packageId for a package-tracked assembly input and to see where a product actually holds stock; for what one package's quantityCost is made of, use distru-get-package. To narrow by kind of product, filter on its category, subcategory, tags, vendor, brand or group instead of resolving productIds first. Quantities are in the package's unit type: quantity is what the package holds (for a sold or transferred package, what it left with); quantityAssembling is held by pending assemblies; quantityActive is the rest, 0 while the package's stock is selling, returning, sold or transferred. quantityActive does not deduct a sales order until it starts selling the package: activeSalesOrder is the non-canceled, non-merged sales order the package is on, null when there is none or the caller cannot see it. quantityCost is the total cost of the package's current quantity whatever its status, not per unit; null when none is recorded or the caller cannot view costs. metrcId and quantityInMetrc (Metrc's quantity at last sync, in Metrc's unit, may be negative) are null outside Metrc. batchNumber is the package's own free-text grouping label, not the linked Distru batch — which batch a package belongs to is batch.name. A null expirationDate means expiry isn't tracked, not that the package won't expire, so never conclude from nulls that nothing is expiring. isActive false = hidden in Distru only, not a Distru status. Packages of deleted or inactive products are never returned.