Sign in
ChargePreset

Upsert a charge preset

Create or update a single charge preset. This is one endpoint for both operations: omit id to create a new preset (responds 201), or pass the id of an existing preset to update it (responds 200). The URL and request shape are identical either way.

On create, name, type, unit_type, and the amount field matching unit_type (percent for PERCENT, price for PRICE) are required. On update the body is sparse — only the fields you send are changed, and any field you omit keeps its current value. Exactly one amount field may be set at a time: to switch a preset from PERCENT to PRICE, send the new unit_type and price together with percent as null (and vice versa). name must be unique within your company (case-insensitive) among non-deleted presets, and may only contain letters, numbers, underscores, and spaces.

A preset stores its amount as a positive number for both types; when a DISCOUNT preset is applied to an order, the resulting charge line carries the negated amount. Changing a preset never rewrites charge lines already applied from it — each line keeps the values copied at apply time. It only affects future applications, and, when allow_inline_edits is false, which amounts new lines referencing the preset are allowed to carry.

This endpoint writes only the preset itself. It does not touch inventory and never syncs to Metrc or BioTrack.

Required permission: settings_permissions_charge_presets.

post/public/v1/charge-presets

Request body

idstring

ID of an existing charge preset to update. Omit to create a new preset. When given, the matching preset in your company is updated in place; the update is sparse, so only the other fields you send are changed. An ID that doesn't exist for your company returns 404.

namestring required

Display name of the preset (e.g. "Delivery Fee"). Required on create. Must be unique within your company (case-insensitive) among non-deleted presets, and may only contain letters, numbers, underscores, and spaces. Charges applied from the preset copy this name and keep it even if the preset is later renamed. On update, omit to leave unchanged.

type'CHARGE' | 'DISCOUNT' required

Whether an applied line adds to or subtracts from the order total.• CHARGE: adds to the total (e.g. a delivery fee).• DISCOUNT: subtracts from the total; the applied charge line carries the preset's amount negated. Required on create. On update, omit to leave unchanged.

unit_type'PERCENT' | 'PRICE' required

How the preset's amount is expressed.• PRICE: a flat money amount, carried in price.• PERCENT: a percentage of the order subtotal, carried in percent. Required on create. The matching amount field must be set and the other must be null; when changing unit_type on update, send the new amount field and null the old one in the same request.

percentstring

The percentage amount as a positive decimal string greater than 0 and less than 100 (e.g. "10" for 10%), with up to 4 decimal places. Required when unit_type is PERCENT; must be null (or omitted) when it is PRICE. Stored positive even for DISCOUNT presets.

pricestring

The flat money amount as a positive decimal string (e.g. "25.00"). Required when unit_type is PRICE; must be null (or omitted) when it is PERCENT. Stored positive even for DISCOUNT presets.

allow_inline_editsboolean

When true, a charge line applied from this preset may carry a different amount or unit type than the preset (the user applying it needs the preset-charge permission for that document type). When false, applied lines are locked to the preset's exact amount. An applied line's name and type always stay locked to the preset either way. Defaults to false when omitted on create. On update, omit to leave unchanged.

auto_apply_tags_on_sales_ordersboolean

When true, this preset is automatically added to a sales order when a product carrying one of the preset's tags is on it — both in the Distru order form and when an order is created through POST /public/v1/orders. Auto-apply runs on create only: adding items to an existing order later never adds new preset charges. Defaults to true when omitted on create. On update, omit to leave unchanged.

auto_apply_tags_on_purchase_ordersboolean

Same as auto_apply_tags_on_sales_orders, but for purchase orders (the Distru purchase form and POST /public/v1/purchases). Defaults to true when omitted on create. On update, omit to leave unchanged.

tagsstring[]

Tag IDs that trigger the auto-apply behavior — call GET /public/v1/tags to list valid IDs. When sent, the list replaces the preset's complete tag set: any tag left out is removed, and an empty array clears all tags. Omit to leave the current tags unchanged. Defaults to no tags on create. At most 200 IDs may be given.

Response

The updated charge preset

Changes

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