Upsert an order

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.

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.

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.

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

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).

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.

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.

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.

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.

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.

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.

The order's complete set of charges and discounts — the extra lines (fees, discounts, taxes) added on top of the items. Each entry follows the OrderChargeRequest shape.

Replacement semantics: on update the charges you send become the order's entire set — any existing charge you don't include is deleted. Omit the charges field entirely to leave the current charges unchanged; send [] to remove them all. Each charge is matched to an existing one by id — a charge with a new or absent id is added, a charge with a known id is updated, and on a matched charge any field you omit keeps its current value — so sending just {"id": "..."} keeps that charge exactly as it is. You never need to resend a charge's full payload to preserve it; include its id and only the fields you want to change.

Manual charges: provide name, type, unit_type, and the amount. For a PERCENT charge the amount is calculated from the order subtotal and any price you send is ignored; send percent instead.

Preset charges: set charge_preset_id and leave name and type out — Distru fills them from the charge preset. If the preset allows inline edits you may also set unit_type and the amount (price or percent); otherwise send only charge_preset_id. Sending a field the preset controls returns a 400.

charge_preset_id is fixed once a charge exists. Omitting charge_preset_id on an update keeps the charge's current preset, like any other omitted field. But you cannot change it: sending a different charge_preset_id, sending null to detach a preset, or adding a charge_preset_id to a charge that was manual all return a 400. To switch a charge to a different preset or to a manual charge, drop it (omit its id, which deletes it) and add a new charge.

Auto-apply: on order create, presets whose auto-apply tags match the order's products are added automatically (see the preset's auto_apply_tags_on_sales_orders flag); a preset you also send explicitly is applied once. Updates never auto-apply: adding items later does not add new preset charges (existing PERCENT charges still recompute from the new subtotal; fixed-price ones are unchanged). The reverse also holds: an auto-applied charge is never auto-removed — deleting the line items whose product tags added it leaves the charge in place until you drop it yourself (omit its id from a charges update).

The products being sold on this order, one entry per line. Required on create. On update it is optional: omit it to leave the order's existing lines untouched, or send it to fully replace the line set — an existing line whose id you omit is deleted, an entry whose id matches an existing line updates it (fields you omit on the entry keep their current value, so an id-only entry is a no-op), and an entry with a new or omitted id is added. An empty array is rejected because every order must keep at least one item. If the order is matched with a compliance transfer, its package-tracked lines each map one-to-one to a transferred package and cannot be deleted — omitting one is rejected. Each entry follows the OrderItemRequest shape.

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

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.

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.

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

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

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

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.

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.