Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cartally.co/llms.txt

Use this file to discover all available pages before exploring further.

Here you can find instructions on how to install and configure the Cartally AI Search widget in your WooCommerce store.

​
Installation

​
Step 1 — Add the widget script

Add the script to your theme’s footer.php file, just before </body>:
  1. In the WordPress admin, go to Appearance → Theme File Editor.
  2. Open footer.php (or theme-footer.php in block themes).
  3. Paste the following code just before the </body> tag:
<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
></script>
  1. Click Update File.
Tip: To prevent losing the script after a theme update, use a child theme. If you’re already using a child theme, edit its footer.php instead.

​
Step 2 — Configure settings in the Cartally panel

  1. Log in to app.cartally.co.
  2. Go to Integration and enter your store’s URL.
  3. Select WooCommerce as the platform.
  4. Provide your Consumer Key and Consumer Secret (generated in WooCommerce → Settings → Advanced → REST API).
  5. Click Save & Connect — Cartally will verify the connection and start syncing products.

​
Generating WooCommerce API keys

  1. In your WordPress admin, go to WooCommerce → Settings → Advanced → REST API.
  2. Click Add key.
  3. Set a Description (e.g., “Cartally”).
  4. Set Permissions to Read.
  5. Click Generate API key.
  6. Copy the Client Key and Private Key — paste them in the Cartally integration panel.
Security: Read-only permissions are sufficient. Cartally never modifies your products or orders.

​
Step 3 — Customize the widget

Go to Widget in the Cartally panel sidebar to set:
  • Accent Color — the main brand color used in the widget UI.
  • Logo URL — a publicly accessible URL to your store’s logo.

​
Widget configuration options

You can customize the widget by adding data- attributes to the script tag:
AttributeDescriptionExample
data-color-accent-primaryAccent color (hex)#e63946
data-logo-urlURL to your shop logohttps://myshop.com/logo.png
data-languageForce a specific languageen
data-currencyForce a specific currencyUSD
data-trigger-selectorCSS selector for custom trigger elements.search-btn

​
Full example with all options

<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
  data-color-accent-primary="#e63946"
  data-logo-url="https://myshop.com/wp-content/uploads/logo.png"
  data-language="en"
  data-currency="USD"
  data-trigger-selector=".cartally-trigger, .header-search-btn"
></script>

​
Automatic language and currency detection

The widget automatically detects the language and currency that the customer is currently using, so you typically don’t need to set data-language or data-currency manually. On WooCommerce the widget reads:
  • Language — from the <html lang="..."> attribute (set by WordPress based on the active locale or WPML/Polylang plugin).
  • Currency — from the .woocommerce-Price-currencySymbol element on the page and maps the symbol to an ISO code (e.g., $ → USD, € → EUR, zł → PLN).
This means if your store uses a multi-currency plugin (e.g., WPML, Aelia Currency Switcher, or Currency Switcher for WooCommerce), the widget will match the customer’s current selection.
You can override the automatic detection by explicitly setting data-language and data-currency on the script tag. This is recommended if your multi-currency plugin does not render .woocommerce-Price-currencySymbol on every page.

​
Attaching the widget to any element

The widget can be triggered by any element on the page — a button, link, icon, or any other HTML element. You choose the element by providing its CSS class or ID in the data-trigger-selector attribute.

​
Option A — Use data-trigger-selector on the script tag

Specify a CSS selector (class or ID) that matches the element(s) you want to use as the widget trigger: 
<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
  data-trigger-selector=".my-search-button"
></script>
You can pass multiple selectors separated by commas: 
data-trigger-selector=".search-btn, #header-search, .mobile-search-icon"

​
Option B — Add a class directly to the element

If you prefer, add the cartally-trigger class to any element in your theme: 
<!-- Using a class -->
<a href="#" class="search-icon cartally-trigger">Search</a>

​
Common WooCommerce theme selectors

ThemeSelector
Storefront.site-search, .site-header .search
Astra.ast-search-icon, .astra-search-icon
OceanWP#searchform-header .search-toggle
Flatsome.icon-search, .searchform-wrapper
GeneratePress.navigation-search
Tip: To find the correct selector for your theme, right-click the search element in your browser → Inspect → note the class or id of the element.

​
Multilingual support

Cartally automatically detects and indexes products in all languages configured in your WooCommerce store.
  • Search works in the language currently selected by the customer.
  • Autocomplete suggestions match the store’s active language.
  • Compatible with WPML, Polylang, and TranslatePress.
  • If a product is not translated, the store’s default language is used.

​
Currencies and localization

Cartally supports currencies configured in your store.
  • Customers always see prices in their currently selected currency.
  • The widget auto-detects the active currency from the page.
  • If a price is not available in a given currency, the store’s default currency is used.

​
Product synchronization

Products are synchronized with Cartally via the WooCommerce REST API.
  • An initial full sync runs when you first connect the integration.
  • Subsequent syncs run periodically to keep the catalog up to date.
  • You can trigger a re-sync from the Integration page in the Cartally dashboard.

​
Troubleshooting

​
Widget does not appear

Check if:
  • The script tag is present in the page source (View Source or F12 → Elements).
  • The src URL (https://app.cartally.co/widget.js) is not blocked by a Content Security Policy, ad blocker, or security plugin (e.g., Wordfence).
  • There are no JavaScript errors in the browser console (F12 → Console).
  • If using a caching plugin, clear the cache after adding the script.
Check if:
  • The product is published (not draft or private).
  • The product has a name and description.
  • The WooCommerce REST API keys have Read permissions.
  • The sync job has completed (check Integration page in the Cartally panel).
  • Your site is accessible from external servers (not blocked by .htaccess, Cloudflare firewall rules, or IP restrictions).

​
Wrong language or currency

If the widget shows the wrong language or currency:
  • Check document.documentElement.lang in the browser console — it should match the active language.
  • Check if .woocommerce-Price-currencySymbol is present on the page (inspect a product price element).
  • If detection fails, set data-language and data-currency explicitly on the script tag.

​
AI does not respond or is slow

Possible reasons:
  • The AI request limit has been reached.
  • There is temporary system overload.
  • The query is very complex.
Solution: Check Dashboard → Usage Overview → AI Requests in the Cartally panel.

​
Caching conflicts

If the widget behaves inconsistently:
  • Exclude widget.js from caching in your performance plugin (WP Super Cache, W3 Total Cache, LiteSpeed Cache).
  • The widget script has defer so it should not block page rendering.
  • If using Cloudflare Rocket Loader, add data-cfasync="false" to the script tag.