> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Help shoppers choose products

> Help a shopper narrow a product choice, then offer the matching product page. The worked example uses Shopify’s live catalog lookup; an approved product description in…

Help a shopper narrow a product choice, then offer the matching product page. The worked example uses Shopify’s live catalog lookup; an approved product description in Knowledge can add detail but does not establish current stock.

For other stores, use [WooCommerce product discovery](/docs/guides/integrations/woocommerce/overview#finding-products), [Wix’s versioned catalog](/docs/guides/integrations/wix-stores/overview#finding-products) or [Squarespace approved products](/docs/guides/integrations/squarespace-commerce/overview#finding-products). Keep each provider’s variant, currency and availability rules with its returned facts.

## Before you begin

- A dedicated test project and a [verified Shopify connection](/docs/documentation/build/tools/shopify#connecting-shopify) for connector examples. Use your actual store values instead of the fictional Northstar examples.
- Two known products with different properties and a product handle you can verify.

#### Studio

Open the test project in [Agent studio](https://creator.voiceflow.com).

#### Developer

Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with access to your test project and Environment. Keep it on your backend or development machine. Set:

```sh
export VF_TOKEN='YOUR_VOICEFLOW_BEARER_TOKEN'
export PROJECT_ID='YOUR_TEST_PROJECT_ID'
export ENVIRONMENT='main'
```

Use a current [Voiceflow CLI](/docs/cli/install) if you choose CLI. API and CLI examples use the Environment's saved Draft. Standalone execution does not attach a tool, compile an agent or publish a release.

## Find and compare candidates

### 1. Collect the requirements

Ask about the product type, intended use and preferences. Separate firm requirements from preferences; keep customer contact and payment data out of product search.

For this test, ask for a **lightweight cotton shirt for short hikes** and compare two products in **Shirts**.

### 2. Look up the products

#### Studio

Add **Shopify → Get products** to the relevant Playbook or **Global tools**. Set a Trigger that explains when to search, then set **productType** to **Shirts** with **limit** 3 for the worked comparison. Run the shopper's question and inspect the tool result.

Inspect product candidates before comparing or recommending them. — Inspect product candidates before comparing or recommending them.

#### Developer

#### API

```sh
curl --fail-with-body --silent --show-error \
  --request POST "https://realtime-api.voiceflow.com/v1/stable/integration/shopify/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "toolName": "shopify_get_products",
  "inputs": {
    "productType": "Shirts",
    "limit": 3
  }
}'
```

#### CLI

```sh
vf integration execute --output-format json --integration shopify \
  --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-name shopify_get_products \
  --inputs '{
  "productType": "Shirts",
  "limit": 3
}'
```

Require `success: true`, `error: null` and `truncated: false` before using `output.data`. An HTTP 200 alone does not establish a successful action. Inspect `output.data.products.edges[].node`; do not treat a transport response as a product match.

### 3. Compare returned facts

Check each candidate’s handle, title, status and storefront link. Compare only facts in the result or approved Knowledge. This fictional result illustrates the comparison; use your store’s actual facts and prices:

| Product | Material and use | Returned price |
| --- | --- | --- |
| Trail shirt | Lightweight cotton; short hikes | CAD 49–59 range |
| Everyday shirt | Heavier cotton; casual wear | CAD 39 |

Recommend the Trail shirt because it meets the stated hiking preference. Preserve the currency and distinguish a price range from a variant price.

Get products combines filters with **OR** and reports aggregate inventory. It does not establish size-specific stock.

### 4. Offer the next useful action

Show the matching product link and explain which requirements it meets. If a variant cannot be confirmed, ask the shopper to select it on the product page. Use [Create a shopping link](/docs/guides/integrations/commerce/create-a-shopping-link) only when the merchant has supplied the exact approved variant mapping.

## Verify the recommendation

#### Studio

Illustrative test: compare both product candidates against the shopper’s hiking preference. — Illustrative test: compare both product candidates against the shopper’s hiking preference.

- **Known match:** name the matching product and the returned facts supporting it.
- **Unmet requirement:** explain the mismatch without inventing another product or availability.
- **Empty result:** say that no match was confirmed and offer the store or support path.

If `hasNextPage` is true, the returned set is incomplete. The connector does not accept a pagination cursor.

### The results are broader than expected

Check OR-based search and the actual products before changing the recommendation.

Use one exact handle for a known product. Multiple filter clauses broaden the search. Inspect each result against the shopper's requirements rather than assuming all filters were enforced together. [Finding products](/docs/documentation/build/tools/shopify#finding-products) documents the connector's complete fields and limits.
