Skip to main content

Substitute finder

A button on the quote editor that finds substitutes for quote lines that cannot be delivered as quoted. You pick a substitute per line and the agent swaps it into the quote, so you keep the sale instead of splitting it off.

Runs: Embedded in Propeller · Trigger: Button · Difficulty: Medium

What you need​

  • An n8n account. See Set up n8n.
  • A Propeller API key.
  • Owner access on the Configuration role to create the agent.

How it works​

You open a quote, click the Workflows button and run the agent. The workflow checks every line and finds the ones that need a substitute:

  • The product has a status that needs one: by default Not available, Phase out or Out of stock.
  • The product cannot be ordered.
  • The product has less stock than the quantity on the line.

For each of those lines it looks for substitutes in your catalogue: products set as an alternative to it, products in the same cluster, in the same category and of the same brand. It searches as the quote's contact, so the customer's order lists and prices apply. A substitute is always available, orderable and priced for this customer. When you keep stock in Propeller, it also has stock for the full quantity.

The agent ranks the substitutes on those signals, on matching attributes and product names, on what the company bought in the last 180 days and on the price difference. Each suggestion shows the customer's price, the difference with the current line, the stock and why it was chosen. A product that only shares the brand or a broad category is not suggested.

You answer with your choice per line, for example 1a or 1a 2b. Yes takes the first suggestion for every line, no leaves the quote as it is. The agent adds each substitute in the place of the old line, with a note that says which product it replaces, removes the old line and saves the quote. If adding a substitute fails, nothing is removed.

To see substitutes for a line that has nothing wrong with it, type its SKU.

Saving the quote replaces the version open in your editor. Reload the page in your browser to see the swapped lines.

Before you adapt it​

  • Check the statuses in the Settings node against how you use product statuses: NEEDS_SUBSTITUTE_STATUSES for the lines that need a substitute and SUBSTITUTE_STATUSES for the products that may replace them. See Product details.
  • If you don't keep stock in Propeller, set CHECK_STOCK to false. Otherwise every line would look out of stock.
  • Set PURCHASE_STATUSES to the statuses of your real orders. See Order statuses.
  • The replies are in English. Set LANGUAGE to NL in Settings for Dutch. Yes and no also work as ja, nee, oui and non.

Install it​

  1. In n8n, import the downloaded JSON as a new workflow.
  2. On the Webhook node, set a basic auth credential (a username and password you choose) and copy the production URL.
  3. Create a header auth credential with your Propeller API key and select it on the four GraphQL nodes.
  4. In the Settings node, check the statuses, CHECK_STOCK, the language and CURRENCY.
  5. Activate the workflow.
  6. Go to Admin > Agents and create an agent with Trigger Button and Interaction Mode Multi Turn. Under Types, pick SALES_HUB_QUOTE_EDITOR. Give the button a label such as "Find substitutes". Paste the webhook URL and the same basic auth values. See AI Agents.
  7. Open a quote with a line that has less stock than its quantity, click the Workflows button, run the agent and answer with your choice.
Filling in your API key

In n8n, create a credential of type Header Auth and fill in its two fields exactly like this:

FieldWhat to fill in
NameapiKey
ValueYour Propeller API key

Name is not a title you pick yourself. It has to say exactly apiKey, otherwise the workflow cannot sign in. See Set up n8n for the full steps.

Placement matters

An agent type is the page where the agent appears. Stick to the types listed in the install steps: the workflow depends on the data that page sends along, so placing the agent on other pages may not work.

Make it yours​

  • Better suggestions: set products as Alternatives to each other on the Storefront tab of a product. Those always come first. See Product details.
  • What counts as alike: set MATCH_ATTRIBUTES to the attributes that decide a substitute in your catalogue, such as volume, voltage or color. By default every attribute both products have counts.
  • More or fewer suggestions: MAX_SUBSTITUTES (default 3) and HISTORY_DAYS (default 180) in Settings.
  • Order quantities: a substitute gets the quantity of the line, raised to its minimum order quantity. Set UNIT_IS_ORDER_MULTIPLE to true only if the unit field of your products means "order in multiples of".
  • The line note: set ADD_LINE_NOTE to false to leave it out.

Limits​

  • The first 100 products of a quote are checked, main lines only, not child items.
  • Each category, brand and cluster search reads up to 50 products.
  • Quantities are not converted between pack sizes: a 6-pack that replaces 10 bottles gets quantity 10. Check the quantity before you send the quote.
  • The suggested price is this customer's price for one piece. The quote calculates volume prices after the swap. A line with a manual price gets the customer's price, and the agent says so.

Use it outside n8n​

Copy the JSON into an AI assistant and follow Adjust a workflow with an AI assistant.

Good to know

The workflows and agents in the Agent Hub are free to use and adapt. They are examples, not supported product features, so test them in a staging environment and check the results before using them in production.