Upsert a price tier
Create a price tier when id is absent, update it in place when present. Every write records a
new immutable version and points the tier's current_version_id at it, so order items priced
by an earlier version keep their frozen pricing (see price_tier_version on the
sales order item).
Updates are sparse: only the fields you send change, and anything you omit is left as-is. This
applies to conditions too — send only the conditions you want to change, and send an empty
array (or null) for a one_of_*/not_one_of_* list to clear that one. Omitting menu_ids leaves the
tier's current menus untouched; send the full list to replace them. When you send the
min_quantity or total_thc_percentage_range object, include every sub-field — a present
sub-field may be null, but a missing one is rejected. Send the object as null to clear it.
conditions decides whether the tier can apply to a sales order item — every populated
condition must be met together (AND), or the tier is not applicable. Within a single "one of"
list any listed match qualifies; a "not one of" list disqualifies any listed match;
min_quantity is compared against the combined quantity of the order's matching items; and
total_thc_percentage_range applies only where selling by potency is enabled. A create must
resolve to at least one condition, otherwise it is rejected with a 400. Creating a tier also
requires your company to be set up for price tiers; if it is not, the create fails with a 400
and a message to contact Distru support.
Saving a tier also refreshes buyer-facing and statewide marketplace price discovery, which happens asynchronously — a 200/201 reflects the saved tier itself, not yet its propagation to every menu or marketplace surface that shows it. When a promo-enabled tier newly becomes eligible for a menu, that menu gets a fresh promo entry.
Promo card fields default sensibly on create: omit menu_promo_card_type and it becomes TEXT,
and a TEXT card fills menu_promo_card_background_hex and menu_promo_card_text_hex with
default colors when you omit them. Send menu_promo_card_type: "IMAGE" for an image card, where
the hex colors are optional. menu_promo_enabled (default false) controls whether the card shows
on menus.
Required permission: settings_permissions_price_tiers, and price tier visibility other than
"Restrict access" on your teams (admins are always allowed).
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
application/json- body
id?stringPrice tier ID to update. Omit to create a new tier; when present, that tier is updated in place and a new immutable version is recorded. An unknown or soft-deleted tier returns 404, and one your team restrictions hide returns 403.
name*stringInternal name of the tier, up to 255 characters. Required.
external_name?stringBuyer-facing name shown on menus and marketplace surfaces, up to 255 characters. When omitted or null, buyer-facing surfaces fall back to name.
price_or_percent*stringWhether the discount is a fixed amount (PRICE, uses price) or a percentage (PERCENT, uses percent). SCREAMING_CASE. A tier carries exactly one — setting one clears the other. Required.
"PRICE""PERCENT"price?stringDiscount amount, as a decimal string with up to 5 decimals (e.g. "10.00"). Its effect depends on is_flat: when is_flat is false it is subtracted from the order item's base price; when is_flat is true it replaces the base price outright. Must be zero or greater. Required when price_or_percent is PRICE; leave unset for PERCENT, which clears it automatically.
percent?stringDiscount percentage off the base price, as a decimal string with up to 3 decimals (e.g. "12.5", 0-100). Required when price_or_percent is PERCENT; switching to PRICE clears it automatically.
is_flat?booleanWhether price is a flat replacement price (true) rather than an amount subtracted from the base price (false). Defaults to false. Can only be true with price_or_percent PRICE — true with PERCENT is rejected.
valid_from_datetime?stringISO8601 UTC start of the active window (e.g. "2026-01-01T00:00:00Z"). Null or omitted means no start bound. Outside the active window the tier is still listed but never applies to orders.
valid_until_datetime?stringISO8601 UTC end of the active window (e.g. "2026-12-31T23:59:59Z"). Null or omitted means no end bound (never expires). Must be after valid_from_datetime when both are set.
menu_mode*stringWhich menus the tier appears on: ALL every menu, NONE no menus, SPECIFIC only the menus in menu_ids. Required, SCREAMING_CASE. Setting ALL or NONE clears any specific menu selection.
"ALL""NONE""SPECIFIC"menu_ids?array<string>IDs of the menus the tier appears on, used only when menu_mode is SPECIFIC (ignored for ALL/NONE, whose selection is cleared). Omit to leave the tier's current menus unchanged; send the full list to replace them — a sent list is the complete set, so menus not in it are removed.
menu_promo_enabled?booleanWhether a promo card for this tier shows on menus. Defaults to false. When true, menu_promo_card_type is required, and a TEXT card additionally requires both hex colors.
menu_promo_card_type?stringPromo card style, SCREAMING_CASE. Defaults to TEXT when omitted on create. A TEXT card requires both hex colors (filled with defaults if omitted on create); an IMAGE card does not use the hex colors. TEXT is the standard style.
"TEXT""IMAGE"menu_promo_card_background_hex?stringPromo card background color as a hex string (e.g. "#9F60FF"). Required for a TEXT card — defaults to a standard color when omitted on create; ignored for IMAGE.
menu_promo_card_text_hex?stringPromo card text color as a hex string (e.g. "#0D1D23"). Required for a TEXT card — defaults to a standard color when omitted on create; ignored for IMAGE.
menu_promo_card_emoji?stringEmoji shown on the promo card. Optional; null for none.
owner_id?stringID of the user that owns this tier. Must be a user you are allowed to assign (within your team-visibility scope); an unassignable id is rejected. Send null to clear ownership; omit to leave it unchanged.
conditions?The conditions to set on a price tier. Send id arrays for each criterion the tier should apply to (one_of_) or be excluded from (not_one_of_). On update this is sparse: only the conditions you include change, and sending an empty array or null clears that one. A create must resolve to at least one condition.
The updated price tier
*/*- response
A single price tier
data?A price tier lowers the price of a single sales order item when the item meets the tier's conditions. It is applied per order item, not at the order level.
curl -X POST 'https://app.distru.com/public/v1/price-tiers' \ -H 'Content-Type: application/json' \ -d '{ "conditions": { "min_quantity": { "quantity": 10, "unit_type_id": "00000000-0000-0000-0000-000000004513" }, "one_of_product_category_ids": [ "00000000-0000-0000-0000-000000000127" ], "one_of_product_tag_ids": [ "00000000-0000-0000-0000-000000000024" ], "total_thc_percentage_range": { "max": 20, "min": 5 } }, "external_name": "VIP Discount", "menu_ids": [ "00000000-0000-0000-0000-00000000003e" ], "menu_mode": "SPECIFIC", "name": "VIP Flower", "percent": "15.125", "price": "5", "price_or_percent": "PERCENT"}'{ "data": { "conditions": { "min_quantity": { "quantity": "string", "unit_type": { "id": "string", "name": "string" } }, "not_one_of_companies": [ { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" } ], "not_one_of_company_groups": [ { "id": "string", "name": "string" } ], "not_one_of_product_brands": [ { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" } ], "not_one_of_product_categories": [ { "id": "string", "name": "string", "official_product_category_id": "string" } ], "not_one_of_product_groups": [ { "id": "string", "name": "string" } ], "not_one_of_product_subcategories": [ { "id": "string", "name": "string" } ], "not_one_of_product_tags": [ { "id": "string", "name": "string" } ], "not_one_of_products": [ { "batches_with_active_quantity_by_location": [ { "batches": [ { "batch_number": "string", "id": "string", "name": "string", "quantity_active": "string" } ], "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" } } ], "bill_of_materials": { "costs": [ { "cost_type": { "cost_per_unit": "string", "id": "string", "name": "string", "unit_type": { "id": "string", "name": "string" } }, "description": "string", "id": "string", "quantity": "string" } ], "description": "string", "dynamic_inputs": [ { "id": "string", "product_categories": [ { "id": "string", "name": "string", "official_product_category_id": "string" } ], "product_groups": [ { "id": "string", "name": "string" } ], "product_subcategories": [ { "id": "string", "name": "string" } ], "quantity": "string", "strains": [ { "id": "string", "inserted_datetime": "string", "name": "string", "strain_type": "INDICA", "updated_datetime": "string" } ], "tags": [ { "id": "string", "name": "string" } ], "unit_type": { "id": "string", "name": "string" } } ], "id": "string", "name": "string", "product_inputs": [ { "id": "string", "product": {}, "quantity": "string" } ] }, "brand": { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" }, "category": { "id": "string", "name": "string", "official_product_category_id": "string" }, "creator": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "custom_data": [ { "id": 0, "name": "string", "value": "string" } ], "deleted_at": "string", "description": "string", "description_markdown": "string", "external_name": "string", "gross_weight": "string", "gross_weight_unit_type": { "id": "string", "name": "string" }, "id": "string", "images": [ { "id": "string", "name": "string", "rank": 0, "url": "string" } ], "inserted_datetime": "string", "inventory_tracking_method": "PACKAGE", "is_active": true, "is_featured": true, "leaflink_product_id": 0, "menu_visibility": "DO_NOT_INCLUDE", "menus": [ { "id": "string", "name": "string" } ], "msrp": "string", "name": "string", "owner": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "packages_with_active_quantity_by_location": [ { "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" }, "packages": [ { "batch_number": "string", "compliance_label": "string", "distru_status": "ACTIVE", "id": "string", "license_id": "string", "location_id": "string", "metrc_id": 0, "quantity": "string", "quantity_active": "string" } ] } ], "product_group": { "id": "string", "name": "string" }, "quantity_active": "string", "quantity_active_by_location": [ { "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" }, "quantity": "string" } ], "quantity_available": "string", "quantity_available_threshold_max": "string", "quantity_available_threshold_min": "string", "quantity_reserved": "string", "sku": "string", "strain": { "id": "string", "inserted_datetime": "string", "name": "string", "strain_type": "INDICA", "updated_datetime": "string" }, "subcategory": { "id": "string", "name": "string" }, "tags": [ { "id": "string", "name": "string" } ], "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "total_cannabinoid_unit": "string", "total_cbd": "string", "total_thc": "string", "treez_wholesale_price": "string", "unit_cost": "string", "unit_net_weight": "string", "unit_net_weight_serving_size_unit_type": { "id": "string", "name": "string" }, "unit_price": "string", "unit_serving_size": "string", "unit_type": { "id": "string", "name": "string" }, "units_per_case": "string", "upc": "string", "updated_datetime": "string", "vendor": { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" }, "wholesale_unit_price": 0 } ], "one_of_companies": [ { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" } ], "one_of_company_groups": [ { "id": "string", "name": "string" } ], "one_of_product_brands": [ { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" } ], "one_of_product_categories": [ { "id": "string", "name": "string", "official_product_category_id": "string" } ], "one_of_product_groups": [ { "id": "string", "name": "string" } ], "one_of_product_subcategories": [ { "id": "string", "name": "string" } ], "one_of_product_tags": [ { "id": "string", "name": "string" } ], "one_of_products": [ { "batches_with_active_quantity_by_location": [ { "batches": [ { "batch_number": "string", "id": "string", "name": "string", "quantity_active": "string" } ], "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" } } ], "bill_of_materials": { "costs": [ { "cost_type": { "cost_per_unit": "string", "id": "string", "name": "string", "unit_type": { "id": "string", "name": "string" } }, "description": "string", "id": "string", "quantity": "string" } ], "description": "string", "dynamic_inputs": [ { "id": "string", "product_categories": [ { "id": "string", "name": "string", "official_product_category_id": "string" } ], "product_groups": [ { "id": "string", "name": "string" } ], "product_subcategories": [ { "id": "string", "name": "string" } ], "quantity": "string", "strains": [ { "id": "string", "inserted_datetime": "string", "name": "string", "strain_type": "INDICA", "updated_datetime": "string" } ], "tags": [ { "id": "string", "name": "string" } ], "unit_type": { "id": "string", "name": "string" } } ], "id": "string", "name": "string", "product_inputs": [ { "id": "string", "product": {}, "quantity": "string" } ] }, "brand": { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" }, "category": { "id": "string", "name": "string", "official_product_category_id": "string" }, "creator": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "custom_data": [ { "id": 0, "name": "string", "value": "string" } ], "deleted_at": "string", "description": "string", "description_markdown": "string", "external_name": "string", "gross_weight": "string", "gross_weight_unit_type": { "id": "string", "name": "string" }, "id": "string", "images": [ { "id": "string", "name": "string", "rank": 0, "url": "string" } ], "inserted_datetime": "string", "inventory_tracking_method": "PACKAGE", "is_active": true, "is_featured": true, "leaflink_product_id": 0, "menu_visibility": "DO_NOT_INCLUDE", "menus": [ { "id": "string", "name": "string" } ], "msrp": "string", "name": "string", "owner": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "packages_with_active_quantity_by_location": [ { "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" }, "packages": [ { "batch_number": "string", "compliance_label": "string", "distru_status": "ACTIVE", "id": "string", "license_id": "string", "location_id": "string", "metrc_id": 0, "quantity": "string", "quantity_active": "string" } ] } ], "product_group": { "id": "string", "name": "string" }, "quantity_active": "string", "quantity_active_by_location": [ { "location": { "address": "1234 Warehouse Street, Oakland, CA", "id": "02c88a3f-d759-4973-88f9-60049d682524", "license_id": "02c88a3f-d759-4973-88f9-60049d682524", "name": "Warehouse 1" }, "quantity": "string" } ], "quantity_available": "string", "quantity_available_threshold_max": "string", "quantity_available_threshold_min": "string", "quantity_reserved": "string", "sku": "string", "strain": { "id": "string", "inserted_datetime": "string", "name": "string", "strain_type": "INDICA", "updated_datetime": "string" }, "subcategory": { "id": "string", "name": "string" }, "tags": [ { "id": "string", "name": "string" } ], "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "total_cannabinoid_unit": "string", "total_cbd": "string", "total_thc": "string", "treez_wholesale_price": "string", "unit_cost": "string", "unit_net_weight": "string", "unit_net_weight_serving_size_unit_type": { "id": "string", "name": "string" }, "unit_price": "string", "unit_serving_size": "string", "unit_type": { "id": "string", "name": "string" }, "units_per_case": "string", "upc": "string", "updated_datetime": "string", "vendor": { "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c", "name": "Retailer 1", "tasks": [ { "due_datetime": "string", "id": "string", "name": "string", "status": "ACTIVE" } ], "updated_datetime": "string" }, "wholesale_unit_price": 0 } ], "total_thc_percentage_range": { "max": "string", "min": "string" } }, "creator": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "current_version_id": "string", "external_name": "string", "id": "string", "inserted_datetime": "string", "is_flat": true, "menu_mode": "ALL", "menu_promo_card_background_hex": "string", "menu_promo_card_emoji": "string", "menu_promo_card_text_hex": "string", "menu_promo_card_type": "TEXT", "menu_promo_enabled": true, "menus": [ { "id": "string", "name": "string" } ], "name": "string", "owner": { "banned": true, "deleted_at": "string", "email": "string", "full_name": "string", "id": "string", "inserted_datetime": "string", "role": { "id": "string", "name": "string" }, "updated_datetime": "string" }, "percent": "string", "price": "string", "price_or_percent": "PRICE", "updated_datetime": "string", "valid_from_datetime": "string", "valid_until_datetime": "string" }}