# Product card configuration and shopping actions

Present store products in reusable card configurations with product choices and supported shopping actions.

*Release 3.3 · admin, developer, operator, visitor*

**Settings › Commerce › Product Cards** · **Settings › Chat › Themes**

## What it is

**Product Cards** displays products with images, prices, descriptions and available choices. Reusable configurations control how those cards look in chat. Product facts come from the product source; changing the appearance does not change the store's product or price.

## Who uses it and why

- Users with the **Settings** role choose card layouts and apply them to themes.
- Developers supply supported product choices and shopping actions.
- Operators send products during a conversation.
- Visitors select a variant, open the product page or use supported basket actions.

## Where to find it

Open **Settings › Commerce › Product Cards** with the **Settings** role. Select the configuration in **Settings › Chat › Themes** under **Product card configuration**.

Operators see cards in product browsing, message composition and conversation history. Visitors see them in chat.

## How it works

When a visitor chooses a shopping action for a product with options, the card opens an options popup where needed. Selecting the final option does not submit a basket addition. The visitor confirms the addition with the action button. A simple product can be added directly when supported.

Selections survive closing and reopening the popup. Pressing Escape or clicking outside closes it. Unavailable choices are disabled or hidden according to the configuration.

Operator and history views do not perform the visitor's basket actions. A card shows success only after the action confirms completion.

## Configure it

1. Choose **New**, or use **Edit** or **Duplicate** on an existing configuration.
2. Enter **Name** and adjust the layout, image, option and action presentation.
3. Use **Add option rule** under **Individual option appearance** to place a particular option on the card or in the popup.
4. Review the preview and save. Preview selections and basket additions are simulated.
5. Edit the chat theme and select the saved **Product card configuration**.

Changes apply to every theme using that configuration. Duplicate it first when a theme needs its own appearance.

### Settings

| Setting | Where | Applies to | Default | Who can change it | What it does |
|---|---|---|---|---|---|
| Product layout | Settings › Commerce › Product Cards | website | Compact with swatches | Settings role | Chooses Compact with swatches, Compact, Inline options, Hybrid or Product link only. |
| Option controls | Settings › Commerce › Product Cards | website | Swatches when supplied | Settings role | Uses supplied swatches, text buttons or dropdowns for product choices. |
| Visible option rows | Settings › Commerce › Product Cards | website | 1 | Settings role | Sets the number of visible rows of option values, from 1 to 20. |
| Quantity | Settings › Commerce › Product Cards | website | Hidden; add one | Settings role | Hides quantity or displays it in the options popup or on the card. |
| Unavailable values | Settings › Commerce › Product Cards | website | Show with strikethrough | Settings role | Shows unavailable values as disabled choices or hides them. |
| Image fit | Settings › Commerce › Product Cards | website | Contain | Settings role | Fits the whole image within its frame or crops it to cover the frame. |
| Image proportions | Settings › Commerce › Product Cards | website | Square | Settings role | Chooses Square, Portrait or Landscape image proportions. |
| Show action labels | Settings › Commerce › Product Cards | website | Off | Settings role | Adds visible labels to action buttons. |
| Show option headings | Settings › Commerce › Product Cards | website | Off | Settings role | Shows headings above product option controls. |
| Show description | Settings › Commerce › Product Cards | website | On | Settings role | Displays the supplied product description. |
| Show ratings | Settings › Commerce › Product Cards | website | Off | Settings role | Displays ratings when supplied by the product source. |
| Show promotional badges | Settings › Commerce › Product Cards | website | Off | Settings role | Displays promotional badges when supplied by the product source. |
| Product card configuration | Settings › Chat › Themes | website | Default; existing themes can retain Existing theme configuration | Settings role | Selects the reusable configuration used by this theme. |
| Location | Settings › Commerce › Product Cards › Individual option appearance | website | Options popup for a new rule; no rules configured initially | Settings role | Places the matched option on the Card or in the Options popup. |
| Match by | Settings › Commerce › Product Cards › Individual option appearance | website | Option identifier for a new rule; no rules configured initially | Settings role | Matches an individual option rule by Option identifier or Semantic identifier. |
| Appearance | Settings › Commerce › Product Cards › Individual option appearance | website | Swatches when supplied for a new rule; no rules configured initially | Settings role | Chooses swatches, text buttons or a dropdown for the matched option. |
| Visible rows | Settings › Commerce › Product Cards › Individual option appearance | website | 1 for a new rule; no rules configured initially | Settings role | Overrides the visible option rows for the matched option, from 1 to 20. |

### Fields

| Field | Where | Required | What it is for |
|---|---|---|---|
| Name | Settings › Commerce › Product Cards | Yes | Names the reusable configuration, up to 100 characters. |
| Identifier | Settings › Commerce › Product Cards › Individual option appearance | Yes | Identifies the product option for an added rule. Required for each rule you add. |

### Permissions

| Permission | Lets you |
|---|---|
| Settings | Access Product Cards and Themes, subject to Settings permissions. |
| View Only | View configurations without creating, duplicating or saving changes. |

## Limits and good to know

- A missing configuration falls back to defaults. Existing themes without a reusable selection can retain their earlier theme configuration.
- Ratings and badges appear only when the source supplies them.
- Basket controls require a supported action; a layout cannot add shopping capabilities to a provider.
- A card can contain up to 20 product options, 100 values per option and 200 variants. More complex catalogues may need further product detail before selection.

## Depends on and works with

### This feature uses

- **Requires** [Messages and rich content](CHAT-002.md): Cards are delivered as rich message content.
- **Requires** [Rich content in visitor chat](VX-018.md): Rich messages display product cards.
- **Configured in** [Roles and permissions](ADM-008.md): Settings permissions control configuration access.
- **Configured in** [Visitor chat themes and branding](VX-003.md): Themes select a reusable card configuration.
- **Works better with** [Product options and variant selection](COM-008.md): Product lookup and variant selection add current product choices to cards.
- **Works better with** [Store product selection for chat](COM-009.md): Operators browse and compose messages containing product cards.
- **Works better with** [Add to cart from product cards](COM-016.md): Supported storefront actions add the selected variant to the visitor's basket.
- **Works better with** [Product recommendations and purchase tracking](COM-017.md): Recommendations can contain commerce product cards.
- **Works better with** [Product cards in visitor chat](VX-019.md): Provides the visitor's product selection and action experience.

### Used by

- **Required by** [Store product selection for chat](COM-009.md): Commerce results and composed products use Rich Content product cards.
- **Required by** [Add to cart from product cards](COM-016.md): Product cards provide the choices and explicit shopping action.
- **Configures** [Product cards in visitor chat](VX-019.md): Product-card configurations control presentation.
- **Configures** [Rich content in AI replies](AI-026.md): Product Card configurations control product-card appearance in the selected chat theme.
- **Configures** [AI product suggestion settings](AI-027.md): Product Card configurations control how suggested products appear when shared.
- **Configures** [Product options and variant selection](COM-008.md): Product card presentation determines how choices and unavailable values appear.
- **Enhances** [Messages and rich content](CHAT-002.md): Product cards provide a specialised rich message experience.
- **Enhances** [Product search and filters](COM-007.md): Search results can be presented as product cards.
- **Enhances** [Product recommendations and purchase tracking](COM-017.md): Matching suggestions can use product cards.
- **Enhances** [AI commerce functions and access limits](COM-029.md): Product results can be presented through product cards.

## FAQ and troubleshooting

### Why did several themes change together?

They share the edited configuration. Use **Duplicate** and select the new configuration for a separate appearance.

### Why did selecting a size not add the product?

The visitor must confirm the shopping action after choosing the required options.

### Why are ratings missing when Show ratings is on?

The source must supply ratings. The switch controls display only.

### Why can I not save an option rule?

Every rule needs an **Identifier**. Also check whether your **Settings** access is **View Only**.