Create, update or delete a purchase order

Creates, updates or deletes one purchase order. Reaches QuickBooks when your settings sync purchases: saving pushes an order, never a draft, when they sync its status and its total isn't negative (a zero total needs its own setting), and deleting removes its bill.

Inputs

Every tool also takes the common inputs.

Field	Type	Required	Description
action	enum `CREATEUPDATEDELETE`	Yes
id	string	No	Required for UPDATE and DELETE. Resolve via distru-search-purchase-orders (status DRAFT for a draft).
supplierId	string	No	Required for CREATE unless status DRAFT. Supplier company. Changes only while the purchase is a draft, the UPDATE that finishes it included; send supplierLocationId with it, or the old supplier's location stays. Resolve via distru-search-companies.
intakeLocationId	string	No	Required for CREATE unless status DRAFT, and to add lines: new lines are received here. Changes only while the purchase is a draft, the UPDATE that finishes it included; a draft's lines move with it. Resolve via distru-search-locations.
status	enum `DRAFTPENDINGPROCESSINGDELIVERINGPARTIALLY_RECEIVEDCOMPLETED`	No	CREATE defaults to PENDING. DRAFT: still being filled in; CREATE needs only the status and required custom fields. An UPDATE to another status finishes it, and the fields CREATE requires are then required. Nothing goes back to DRAFT. PENDING: placed, waiting on the supplier. PROCESSING: the supplier is preparing it. DELIVERING: on its way. These three leave stock alone. PARTIALLY_RECEIVED: part arrived; every line needs receivedQuantity, which is added to stock; not for package-tracked products. COMPLETED: everything arrived and is added to stock; package-tracked products complete only by matching a Metrc manifest. A received purchase cannot go back to PENDING, PROCESSING or DELIVERING.
orderDatetime	string	No	When the purchase was ordered. CREATE defaults to now; a draft gets it when finished. ISO 8601 with a UTC offset, e.g. "2026-09-01T00:00:00-07:00"; the company timezone is on distru-get-me.
dueDatetime	string	No	When payment is due. A non-draft CREATE, or finishing a draft, defaults to orderDatetime plus the company's default purchase payment term, and needs it when the company has none. ISO 8601 with a UTC offset, e.g. "2026-09-01T00:00:00-07:00"; the company timezone is on distru-get-me.
billingLocationId	string	No	A non-draft CREATE, or finishing a draft, defaults to the company's default purchase billing location, else intakeLocationId. Resolve via distru-search-locations.
supplierLocationId	string	No	The supplier's location the purchase ships from. Resolve via distru-get-company on the supplier.
ownerId	string	No	Resolve via distru-search-users.
description	string	No	Notes. CREATE defaults to the company's default purchase description.
metrcManifestNumber	string	No	Incoming Metrc manifest to match this purchase with; completes it and receives the packages. Every accepted package on the manifest needs one line, identified by metrcPackageLabel. intakeLocationId must be on the license that received it. Not on a draft: finish it first. Resolve via distru-get-metrc-manifest.
orderItems	object[] or null	No	Required for CREATE unless status DRAFT. On UPDATE the complete list: stored lines left out are deleted, and [] is refused unless the purchase is a draft; send a stored line with just its id to keep it unchanged. Omitted or null leaves the lines as they are. Read current rows with distru-get-purchase-order first (includeOrderItems). Not allowed on UPDATE once the purchase is matched to a compliance transfer.
orderItems[].id	string	No	UPDATE only: a line already on the purchase; only the fields sent change. Omit to add a line. Resolve via distru-get-purchase-order (includeOrderItems).
orderItems[].productId	string	No	Resolve via distru-search-products. With metrcPackageLabel, omit it when the manifest package shows package.product (that product is used, a different one is rejected) or productMostRecentlyMappedToMetrcItem.
orderItems[].batchId	string	No	Required for batch-tracked products (inventoryTrackingMethod BATCH), except on a draft until it is finished; product-tracked ones use their default batch, package-tracked ones get a package when received. Resolve via distru-search-batches (filter by productIds).
orderItems[].quantity	string or number	No	In the product's unit type. Not with metrcPackageLabel: it comes from the manifest.
orderItems[].price	string or number	No	Cost per unit of the product's unit type, not the line total. Required for CREATE.
orderItems[].receivedQuantity	string or number	No	Received so far, in the product's unit type. Required on every line with status PARTIALLY_RECEIVED, not allowed otherwise.
orderItems[].metrcPackageLabel	string	No	With metrcManifestNumber: the package's label (tag) on the manifest. The line quantity comes from the manifest, converted to the product's unit type.
orderCharges	object[] or null	No	Order-level charges and discounts: a preset (chargePresetId) or a custom one (name, type, unitType, and percent or price). Taxes not supported. On UPDATE the complete list: stored charges left out are deleted; [] removes them all. Omitted or null leaves the charges as they are. Read current rows with distru-get-purchase-order first (includeOrderCharges). Not allowed on UPDATE once the purchase is matched to a compliance transfer.
orderCharges[].id	string	No	UPDATE only: a charge already on the purchase; only the fields sent change. Omit to add a charge. Resolve via distru-get-purchase-order (includeOrderCharges).
orderCharges[].chargePresetId	string	No	A charge preset; it sets name, type and the amount, so send it alone: unitType, percent and price are refused unless the preset allows inline edits. Resolve via distru-search-lookups (type CHARGE_PRESET).
orderCharges[].name	string	No
orderCharges[].type	enum `CHARGEDISCOUNT`	No
orderCharges[].unitType	enum `PERCENTPRICE`	No
orderCharges[].percent	string or number	No	Percent of the order subtotal for unitType PERCENT, e.g. 10. A custom charge keeps the sign sent, whatever its type: negative for a DISCOUNT, e.g. -10. With chargePresetId, only to override a preset that allows inline edits, and positive.
orderCharges[].price	string or number	No	Flat amount for unitType PRICE. A custom charge keeps the sign sent, whatever its type: negative for a DISCOUNT. With chargePresetId, only to override a preset that allows inline edits, and positive.
customFields	object[]	No	Only the fields listed change. Required custom fields must be set, on update too, while still blank.
customFields[].customFieldId	string	Yes	Resolve via distru-search-custom-fields (entityType PURCHASE_ORDER).
customFields[].value	string or string[]	Yes	TEXT: the text. DROPDOWN: the option name. CHECKBOX: an array of option names. DATE: YYYY-MM-DD, company timezone. "" or [] clears the field.

Output

This tool returns one of 2 shapes, depending on its inputs.

Presence on a nested field assumes its parent exists.

Result with purchaseOrder

Field	Type	Presence	Description
purchaseOrder	object	Always
purchaseOrder.id	string	Always
purchaseOrder.customFields	object[]	Always
purchaseOrder.customFields[].customField	object	Always
purchaseOrder.customFields[].customField.id	string	Always
purchaseOrder.customFields[].customField.name	string	Always
purchaseOrder.customFields[].customField.fieldType	enum `CHECKBOXDATEDROPDOWNTEXT`	Always
purchaseOrder.customFields[].value	string	Can be null
purchaseOrder.purchaseNumber	string	Always
purchaseOrder.status	enum `COMPLETEDDELIVERINGDRAFTPARTIALLY_RECEIVEDPENDINGPROCESSING`	Always
purchaseOrder.paymentStatus	enum `NOT_PAIDOVER_PAIDPAIDPARTIALLY_PAID`	Always
purchaseOrder.total	string	Always
purchaseOrder.totalCharges	string	Always
purchaseOrder.paid	string	Always
purchaseOrder.orderDate	string	Can be null
purchaseOrder.dueDate	string	Can be null
purchaseOrder.createdDate	string	Always
purchaseOrder.updatedDate	string	Always
purchaseOrder.description	string	Can be null
purchaseOrder.url	string	Always
purchaseOrder.supplier	object	Null or absent
purchaseOrder.supplier.id	string	Always
purchaseOrder.supplier.name	string	Null or absent
purchaseOrder.owner	object	Can be null
purchaseOrder.owner.id	string	Always
purchaseOrder.owner.profile	object	Always
purchaseOrder.owner.profile.fullName	string	Always
purchaseOrder.intakeLocation	object	Can be null
purchaseOrder.intakeLocation.id	string	Always
purchaseOrder.intakeLocation.name	string	Always
purchaseOrder.intakeLocation.address	string	Always
purchaseOrder.billingLocation	object	Can be null
purchaseOrder.billingLocation.id	string	Always
purchaseOrder.billingLocation.name	string	Always
purchaseOrder.billingLocation.address	string	Always
purchaseOrder.supplierLocation	object	Can be null
purchaseOrder.supplierLocation.id	string	Always
purchaseOrder.supplierLocation.name	string	Always
purchaseOrder.supplierLocation.address	string	Always
purchaseOrder.qbBillId	string	Can be null
purchaseOrder.qbSyncStatus	enum `DELETED_IN_QBOERRORNOT_SYNCEDPARTIALLY_SYNCEDPENDINGSYNCED`	Can be null
purchaseOrder.orderItems	object[]	Always
purchaseOrder.orderItems[].id	string	Always
purchaseOrder.orderItems[].quantity	string	Always
purchaseOrder.orderItems[].receivedQuantity	string	Can be null
purchaseOrder.orderItems[].price	string	Always
purchaseOrder.orderItems[].product	object	Always
purchaseOrder.orderItems[].product.id	string	Always
purchaseOrder.orderItems[].product.name	string	Always
purchaseOrder.orderItems[].product.unitType	object	Always
purchaseOrder.orderItems[].product.unitType.id	string	Always
purchaseOrder.orderItems[].product.unitType.name	string	Always
purchaseOrder.orderItems[].batch	object	Can be null
purchaseOrder.orderItems[].batch.id	string	Always
purchaseOrder.orderItems[].batch.name	string	Always
purchaseOrder.orderItems[].location	object	Can be null
purchaseOrder.orderItems[].location.id	string	Always
purchaseOrder.orderItems[].location.name	string	Always
purchaseOrder.orderItems[].package	object	Can be null
purchaseOrder.orderItems[].package.id	string	Always
purchaseOrder.orderItems[].package.metrcLabel	string	Always
purchaseOrder.orderCharges	object[]	Always
purchaseOrder.orderCharges[].id	string	Always
purchaseOrder.orderCharges[].name	string	Always
purchaseOrder.orderCharges[].type	string	Always
purchaseOrder.orderCharges[].unitType	string	Always
purchaseOrder.orderCharges[].percent	string	Can be null
purchaseOrder.orderCharges[].price	string	Always
purchaseOrder.orderCharges[].isTax	boolean	Always
purchaseOrder.complianceManifestNumber	string	Can be null	Manifest number of the matched compliance transfer; null when unmatched.

Result with id

Field	Type	Presence
id	string	Always

What the AI reads

Creates, updates or deletes one purchase order: a purchase of inventory from a supplier, with line items, order-level charges and custom fields. Stock changes only once it is PARTIALLY_RECEIVED or COMPLETED (UPDATE status COMPLETED receives everything). For a purchase still being filled in, CREATE status DRAFT; an UPDATE to another status finishes it. Payments: distru-create-purchase-payment. When the company syncs purchases to QuickBooks, a CREATE or UPDATE that leaves the purchase in one of the company's QuickBooks sync statuses (by default only COMPLETED) creates or updates its QuickBooks bill, and the vendor when missing. To import an incoming Metrc manifest, CREATE with metrcManifestNumber and one line per accepted package (metrcPackageLabel), read from distru-get-metrc-manifest (includeDeliveries); the purchase is created COMPLETED and receives the packages. Otherwise CREATE, or the UPDATE that finishes a draft, adds the preset charges whose auto-apply tags match the products and aren't on it yet. On UPDATE, setting metrcManifestNumber matches the purchase with an incoming Metrc manifest and completes it: a stored line sent with its id and a metrcPackageLabel keeps its price, and its product unless the package is already in Distru as another product; once matched to a compliance transfer, only header fields change. DELETE removes the purchase for good (purchases have no canceled status; drafts included) with its lines, charges, tasks, every payment (voided ones included) and the AI purchase intake that created it, and deletes its QuickBooks bill and bill payments. Stock it received is taken back out first, so DELETE is refused when that stock was already sold, transferred, adjusted or assembled; purchases synced to Metrc are refused too. CREATE and UPDATE return the purchase as distru-get-purchase-order does with includeOrderItems and includeOrderCharges; DELETE returns its id. Sparse update: on UPDATE only the fields passed change; orderItems and orderCharges, when passed, replace the whole list.