Inventory and Purchasing

Choose the Product

Search Products before creating a new record. Adopt an approved catalog entry when it matches, or create a custom workspace product. Product defaults and targets are specific to your workspace.

Import Catalog Products

Coil administrators can add approved global catalog products at Admin > Catalog by pasting JSON into Paste JSON or choosing a JSON file. Both inputs accept an array of product objects or an object with a products array, with at most 250 products. Choose Preview JSON for pasted text, review the products, and confirm Add products. Invalid JSON or product fields block the import; editing pasted text clears its preview so it must be reviewed again. Importing catalog products does not create workspace inventory.

Record a Purchase

For receipt items, productSubtotal and salesTaxAmount are per lot. unitCount is units per lot; lotQuantity multiplies the number of lots. Check the receipt's purchase quantity rather than assuming a pack or case equals one sellable unit.

When a linked receipt has tax but a lot has no tax amount, Sales Tax Needs Review asks you to allocate the tax paid to that lot. If no tax was charged for the item, keep the amount at $0.00 and choose Confirm $0.00. This records that you reviewed the lot without marking sales tax as paid; the warning then disappears. Existing lots with positive tax amounts or salesTaxPaid already set remain treated as reviewed.

1. Select the product, supplier/source, acquisition date, quantity, and price paid.
2. Record sales tax and shipping separately so the landed cost is allocated across the lot's units.
3. Set expiration on the lot where applicable. Use documented cost basis when supported by purchase records, or estimated basis with notes when appropriate.
4. Attach an original receipt or create the purchase through the Receipts workflow. Verify units per lot and the number of lots before creating inventory.

Give Items Away

Giveaways remove inventory with reason gifted, without creating a sale, revenue, card fees, or location commissions. No location is required. Zero-tax events are retained for history; additional liability appears in Use Tax Owed and the period CSV. This is Coil's tracking rule, not tax advice.

The API and MCP use the same tools and require inventory:giveaway, which existing keys must add explicitly. Changed units or purchase-tax evidence invalidate the preview. A mistakenly removed unit can be returned to stock in Inventory, removing its use-tax event. Existing giveaway records are not recalculated.

1. Expand a lot's units in Inventory and choose Mark Removed, then Given away. Select the date and review the additional use tax before saving.
2. If purchase sales tax was already recorded on the lot, the suggested additional use tax is zero. Otherwise Coil applies the selected use-tax rate to the unit's purchase cost, not its retail price. You can review or override the suggestion in the form.
3. For several units through an agent, select exact in-stock IDs with list_inventory, then call preview_giveaway with unitIds, eventDate, and optional taxRate or notes. Review the purchase-tax evidence and additionalUseTax, then approve apply_giveaway using previewId and requestId within 10 minutes.

Storage and Placement

Unassigned in-stock units are warehouse inventory. Assigned units belong to a machine and its location. Use transfers or a restock visit to move existing stock; receiving the same purchase again creates additional units.

Agent-driven movement uses exact unit IDs and preview/apply tools. It does not record sales, change cost basis, or rewrite sold history.

Defaults Versus Existing Stock

Changing a product's default sale price affects future inventory defaults. Existing units retain their own list prices until you change them separately.

For agents, read get_product, update_product with its current updatedAt, then select exact in-stock units for preview_inventory_price and set_inventory_list_price. Sold and removed records are excluded from agent repricing.

Cost and History Corrections

Lot-cost corrections recalculate unit cost basis, including for sold/removed units, and can change reported COGS and historical profit. Review the impact before editing costs. Agents can update a lot with its current expectedUpdatedAt; changes to productSubtotal, salesTaxAmount, or shippingAmount also require confirmHistoricalImpact:true. The transaction recalculates every unit's cost basis and returns the new total/unit cost. Historical sale prices and stock removals are not currently editable through agent tools.

Consume an Item Yourself

The default uses the purchase lot's existing salesTaxPaid flag and salesTaxAmount. A paid flag or positive purchase-tax amount suggests no additional use tax. If neither is recorded, personal use and quality checks default to use tax at the selected rate (0.06 by default). Losses such as expiration or damage do not default to use tax.

Use tax is calculated on the unit's cost basis before its allocated purchase sales tax, not its selling price. The dialog shows the amount before saving. An explicit checkbox override remains available, but no cross-state rate/credit calculation is inferred. These defaults assume paid purchase tax already satisfied the applicable liability and has not been refunded.

The server re-reads the workspace lot when saving. Correct missing purchase-tax data on the lot first; receipt tax that has not been allocated to the lot is not automatically treated as that unit's paid tax. Reverting the unit to in-stock clears its removal details and consumption event.

1. Expand the product/lot and its units in Inventory, then choose Mark Removed on the consumed unit.
2. Select Personal use, enter the consumption date, and review the suggested additional use tax.
3. Save the removal. The item leaves stock without recording revenue or a sale; its removal history is retained even when tax owed is zero.