Sign in
Order

Upsert an order

Create or update a single sales order. Omit id to create a new order (Distru assigns the order number and id); pass an existing order's id to update it. An id that doesn't exist, or belongs to another company, returns a not-found error.

Updates are sparse at the top level: send only the fields you want to change — every field you omit (including status) keeps its current value. The items and charges collections work differently. Omit the whole items (or charges) field and its existing rows are left untouched. Send the field and it fully replaces that set: an existing row whose id you omit is deleted, an entry whose id matches an existing row updates it (omitted fields on that entry are kept from the existing row, so you can patch a single field by sending just its id and the change), and an entry whose id is new (or omitted — Distru then assigns one) is added. Sending items as an empty array removes every line, which an order cannot be left in, so it is rejected. Charges are full-replace on update — see the charges field for how existing charges, presets, and deletions are handled; on create, charge presets whose auto-apply tags match the order's products are added automatically. The whole upsert is atomic: if any part is rejected (a validation error, a disallowed status transition, an unfulfillable line) nothing is changed and the response is a 400 whose errors point at the offending field.

Setting status moves the order through its lifecycle and drives inventory. A PENDING or CANCELED order reserves nothing and touches no inventory; moving to PROCESSING commits sellable inventory — assigning a package or batch to a line item moves that quantity into a committed selling state and any unfulfilled line adds to the product's reserved quantity; READY_TO_SHIP, DELIVERING, DELIVERED, and COMPLETED additionally require every line item to be fulfilled. See the status field on the order for the full per-status behavior and transition requirements.

Compliance: associating the order with a state transfer is one-system-only — send metrc_transfer_id OR biotrack_id, never both. Doing so builds the order from that outgoing Metrc/BioTrack transfer. Any order carrying package-tracked items must be associated with a compliance transfer before it can reach DELIVERING, DELIVERED, or COMPLETED.

Invoicing: set upsert_invoice to create or refresh this order's invoice, and email_invoice to email it. The response returns the saved order with its recomputed total, line items (with cost fields), charges, invoices, and returns.

Required permission: orders_permissions_create to create, orders_permissions_edit (plus access to the order under team restrictions) to update.

post/public/v1/orders

Request body

biotrack_idstring

The BioTrack manifest to associate with this order, building the order from that outgoing BioTrack transfer. Mutually exclusive with metrc_transfer_id — send at most one; an order can be linked to only one compliance transfer.

blaze_payment_type'CASH' | 'CREDIT' | 'DEBIT' | 'COD' | 'ACH_TRANSFER' | 'CHEQUE' | 'OTHER'

The payment type for an order shipping to a Blaze-associated company. Required (and only meaningful) when the order's buyer company is mapped to a Blaze retailer through the Distru integration; leave it off otherwise.

company_idstring

The buyer of this order, as a company relationship ID (the same id in each order's company.id and GET /public/v1/companies). Determines the customer, and drives pricing, default payment term (used to derive due_datetime), and blaze_payment_type requirements. Optional while the order stays PENDING, PROCESSING, or CANCELED, but required to move it to READY_TO_SHIP, DELIVERING, DELIVERED, or COMPLETED. Once a customer is set, you cannot clear it back to null on a later update.

delivery_datetimestring

ISO8601 datetime the order was / will be delivered. Optional; null when the order has no delivery datetime set.

due_datetimestring

The datetime by which the customer is expected to pay for this order. Optional: when omitted, it is derived from the customer's default payment term, then the company default order payment term, then falls back to the order date (COD).

external_notesstring

This is a message that will be shown to the customer on order slips. This is the "Message to Customer" field in the Distru order form.

upsert_invoiceboolean

When true, create an invoice for this order if it doesn't have one yet, or update the existing invoice with the order's latest changes.

email_invoiceboolean

When true, email the order's invoice. No email is sent unless the order has an invoice (see upsert_invoice) and a recipient can be resolved from email_invoice_addresses or the buyer company relationship's invoice email.

email_invoice_addressesstring

Comma-separated list of email addresses to send the invoice to when email_invoice is true. Takes precedence over the company relationship's invoice email. Invalid addresses are rejected.

idstring

ID for this order. Omit it to create a new order — Distru assigns the ID. Provide an existing order's ID to update that order; an ID that doesn't exist returns a not-found error.

order_datetimestring

ISO8601 datetime the order was placed. Required on create — omitting it there returns a validation error; on update, omit to leave the existing value unchanged. This is the field the list endpoint sorts (newest first) and filters on.

internal_notesstring

Free-form notes visible only inside Distru; never shown to the customer. Use external_notes for a customer-facing message.

metrc_transfer_idinteger

The Metrc transfer to associate with this order, building the order from that outgoing Metrc transfer. This is Metrc's own integer transfer id, not a Distru ID. Mutually exclusive with biotrack_id — send at most one; an order can be linked to only one compliance transfer.

location_idstring

The Distru location ID of the order's top-level location — used to filter orders and to associate the order with a compliance (Metrc) license, identifying which Metrc license the order takes place under. It is not the location sale quantities are drawn from; each order item sets that via its own location_id. Optional in general, but required when the order has any package-tracked items, where it must reference a location that has a compliance license and that license must match the license of every package-tracked item's location.

billing_location_idstring

The billing location's ID (a Distru location ID). Optional.

shipping_location_idstring

The shipping location's ID (a Distru location ID). Optional.

owner_idstring

The Distru user that owns this order, as a user ID (the same id in the response's owner.id). Optional.

status'PENDING' | 'PROCESSING' | 'READY_TO_SHIP' | 'DELIVERING' | 'DELIVERED' | 'COMPLETED' | 'CANCELED'

The status to set for this order, controlling where it sits in its lifecycle and how it affects inventory and compliance. Required on create; on update, omit to leave the current status unchanged. See the status field on the order response for what each value means. Note that some transitions have requirements: moving to READY_TO_SHIP, DELIVERING, DELIVERED, or COMPLETED requires every line item to be fulfilled and a customer (company_id) to be set, and DELIVERING/DELIVERED/COMPLETED additionally require a compliance transfer when the order carries any package-tracked items.

custom_dataobject

A map of custom field IDs to their values. Use GET /public/v1/custom-fields?parent_object=order to retrieve available custom fields, their IDs, and their types. The value format depends on the field's type: a text field takes a string, a date field takes a full ISO8601 datetime, and a checkbox field takes an array of its selected options.

Response

A single order

Changes

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