Sign in
StockAdjustment

Insert a stock adjustment

Record a stock adjustment — a manual change to on-hand inventory that isn't a sale, purchase, or transfer (for example waste, theft, damage, a recount, or a reconciliation with the state compliance system).

Identify what to adjust with exactly one of product_id, batch_id, or package_id, matching how the product's inventory is tracked (product-, batch-, or package-tracked). Supplying more than one, or none, is rejected.

There are two adjustment modes, selected by whether you pass package_id:

• Standard adjustment (product_id or batch_id): set quantity in the product's unit type and a source location_id. A positive quantity adds on-hand inventory at that location (recorded as a gain), a negative quantity removes it (recorded as a loss); when reason is waste the quantity moves the stock into a waste state and must be negative. No compliance system is touched, so the change is visible in Distru inventory immediately.

• Compliance adjustment (package_id): set compliance_quantity in the package's unit type and omit location_id — the package's current location is used automatically. The package's tracked quantity is updated and the change is pushed to the connected state traceability system (Metrc or BioTrack) synchronously, as part of this request. A 200 means the compliance system accepted the change; if it rejects it, you get a 400 carrying the compliance error message as a single human-readable string. reason must be one the compliance system accepts for package adjustments.

The whole operation is atomic: if any validation fails or the compliance sync is rejected, nothing is persisted — no inventory moves and the package is left untouched. A compliance adjustment additionally requires the target package to be in an adjustable state — it is rejected if the package is on hold, destroyed, discontinued, inactive, syncing, transferred, finished, scheduled for destruction, assigned to an order, or has unresolved compliance audit discrepancies, and a negative adjustment cannot exceed the package's currently available quantity. For Metrc finished-good packages, an increase also cannot push the quantity above what was received or created for that package (less what has already been used), and count-based packages may be required to stay whole numbers.

Stock adjustments are immutable: once created they cannot be edited or deleted through this API.

Required permission: products_permissions_adjust_inventory. Setting unit_cost additionally requires cost accounting to be enabled for the company and permission to apply costs on quantity adjustments.

post/public/v1/adjustments

Request body

product_idstring

ID of the product to adjust. Provide only when the product is product-tracked. Supply exactly one of product_id, batch_id, or package_id; supplying more than one, or none, is rejected. Choosing product_id or batch_id makes this a standard (non-compliance) adjustment.

batch_idstring

ID of the batch to adjust. Provide only when the batch's product is batch-tracked. Supply exactly one of product_id, batch_id, or package_id. Choosing product_id or batch_id makes this a standard (non-compliance) adjustment.

package_idstring

ID of the package to adjust. Provide only when the product is package-tracked. Presence of package_id switches this into a compliance adjustment: use compliance_quantity instead of quantity, omit location_id, and the change is synced to Metrc or BioTrack. Supply exactly one of product_id, batch_id, or package_id.

quantitynumber

Amount to adjust stock by, expressed in the product's unit type, as a decimal string (e.g. "10" adds ten, "-4" removes four). Required for standard adjustments (product_id/batch_id) and must be omitted when package_id is set (use compliance_quantity instead). Positive adds on-hand inventory, negative removes it. Must be negative when reason is waste. Must be greater than -1000000000.

compliance_quantitynumber

Amount to adjust stock by, expressed in the package's unit type, as a decimal string. Required when package_id is set (a compliance adjustment) and must be omitted otherwise (use quantity instead). Same sign convention as quantity: positive adds, negative removes, and a negative amount cannot exceed the package's currently available quantity. In the response, this value is echoed back as compliance_quantity (package unit type) while quantity carries the same change converted into the product's unit type.

descriptionstring

Free-text note explaining the adjustment. Required for compliance adjustments (package_id set); optional for standard adjustments. Max length 800 characters for standard adjustments and 250 characters for compliance adjustments.

unit_costnumber

Cost per unit applied to the added inventory, as a decimal string. Allowed only for companies with cost accounting enabled and for callers with permission to apply costs on quantity adjustments. Must be omitted when the adjustment quantity is negative (a removal can't be costed). Required for a positive adjustment when the company setting 'Require Cost on Intake and Quantity Adjustments' is on. The value you send is reflected back in the response as unit_cost and drives total_cost.

completion_datetimestring

Effective date/time of the adjustment — surfaced as completion_datetime in the response — as an ISO8601 datetime, e.g. 2022-07-10T00:00:00Z. Required for both standard and compliance adjustments.

reasonstring

Reason for the adjustment. Required. For standard adjustments, one of the lowercase, case-sensitive values waste, stolen, damaged, fire, write-off, expired, lab-testing, revaluation, or other; only waste changes behavior — it forces quantity to be negative and moves the stock into a waste state rather than a plain loss. For compliance adjustments, must be a reason the connected state compliance system (Metrc or BioTrack) accepts for package adjustments; an unrecognized reason is rejected together with the list of valid reasons. Echoed back verbatim as reason in the response.

location_idstring

ID of the source location the adjustment applies to. Required for standard adjustments. Must be omitted for compliance adjustments (package_id set) — the package's current location is used automatically, so setting it is rejected.

Response

The stock adjustment was inserted successfully

Changes

No recorded changes to this endpoint across all 1 revision of this API.