Add an upsell rule
Needs a read and write connection. The assistant finds the real products, shows you what it matched, and only then saves.
Ask: "When someone has the linen shirt in their cart, recommend the linen trousers with 10% off."
Step 1 — Read what already exists
Call get_drawer_settings with sections: ["upsell"]. Rules are checked in order and the first
active rule whose conditions match the cart wins; later matching rules do not run. A new rule is
added at the end, so an earlier rule that already matches the same cart will win over it.
Note the revision that comes back. The assistant sends it as expectedRevision so that a change
made in the app in the meantime is not overwritten.
Step 2 — Resolve the products
Call search_products for the trigger and for the recommendation. It returns title, vendor,
status, handle and product id. If two products match, the assistant should ask which you meant. To
offer only some variants, get_product_variants lists SKUs and options.
Step 3 — Add the rule
add_upsell_rule takes:
| Field | What it is |
|---|---|
name | Up to 60 characters |
status | active or draft. A draft is saved but never shown |
triggerProducts | Up to 20 products that start the rule — or |
triggerConditions | Groups that must all match, each a list of alternatives: product, collection or cart total. [] matches every cart. At most 5 conditions |
recommendedProducts | Up to 5 products, each optionally narrowed to certain variants |
discountEnabled, discountUnit, discountValue | Percentage, fixed amount, or a fixed final price |
Supply exactly one of triggerProducts or triggerConditions. Collections used in a condition
must be published to the Online Store. Cart-total amounts are in the store's currency with at most
two decimals.
Step 4 — Check the result
A saved change returns status: "saved" and the new revision. Ask the assistant to read the rule
back with get_drawer_settings and tell you where it sits in the order. If it needs to run before
another rule, reorder_upsell_rules sets the full order.
If a result says publishPending, the change is saved but not yet on the storefront. The assistant
can check with get_operation_status and re-publish with retry_configuration_publication.
What you finish holding
A rule you can name, its position in the order, and confirmation that it is saved and published. Removing a rule later needs an explicit confirmation from you.