--- title: "Insert a stock adjustment" method: POST path: "/public/v1/adjustments" tags: ["StockAdjustment"] --- # Insert a stock adjustment `POST /public/v1/adjustments` 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. ## Request body - object - `product_id` string — 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_id` string — 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_id` string — 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`. - `quantity` number — 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_quantity` number — 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. - `description` string — 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_cost` number — 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_datetime` string — 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. - `reason` string — 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_id` string — 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 `200` The stock adjustment was inserted successfully ## Other responses - `400` — Invalid parameters - `401` — Missing or invalid API token - `403` — The API token lacks the required permission --- [API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/eb775b7b6ee0/schema)