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 Magento 2 store.

​
Installation

​
Step 1 — Add the widget script

Add the Cartally script to your Magento theme so it loads on every page. Option A — CMS Block (recommended)
  1. In the Magento Admin, go to Content → Blocks → Add New Block.
  2. Set the Block Title and Identifier (e.g., cartally_widget).
  3. Switch to the HTML editor and paste:
<script
  src="https://app.cartally.co/widget.js"
  defer
  data-cartally-widget
></script>
  1. Save the block.
  2. Go to Content → Widgets → Add Widget.
  3. Choose CMS Static Block as the type and your theme.
  4. In Layout Updates, set Display on to “All Pages” and Container to “Before Body End”.
  5. In Widget Options, select the block you created.
  6. Save and clear the cache (System → Cache Management).
Option B — Template file Add the script directly to your theme’s default_head_blocks.xml or footer.phtml: 
<!-- app/design/frontend/YourVendor/YourTheme/Magento_Theme/layout/default_head_blocks.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <head>
        <script src="https://app.cartally.co/widget.js" src_type="url" defer="true" />
    </head>
</page>
After adding, clear the cache: 
bin/magento cache:clean

​
Step 2 — Create an Integration Access Token

Cartally connects to your store using Magento’s Integration feature, which provides a permanent access token with scoped permissions.
  1. In the Magento Admin, go to System → Integrations.
  2. Click Add New Integration.
  3. Set the Name to Cartally (or any name you prefer).
  4. Go to the API tab.
  5. Under Resource Access, select Custom and enable only read access to these resources:
    • Catalog → Inventory → Products (read)
    • Stores → Settings → All Stores (read)
    • Stores → Currency (read)
  6. Click Save and then Activate.
  7. In the confirmation dialog, click Allow.
  8. Copy the Access Token — you will paste it in the Cartally panel.
Keep the Access Token secure. It grants read access to your product catalog. Never share it publicly or commit it to version control.
Security: Only read permissions are required. Cartally never modifies your products, orders, or any other data.

​
Step 3 — Configure settings in the Cartally panel

  1. Log in to app.cartally.co.
  2. Go to Integration and enter your store’s URL (e.g., https://your-store.com).
  3. Select Magento as the platform.
  4. Paste the Access Token from Step 2 into the API Key field.
  5. Click Save & Connect — Cartally will verify the connection and start syncing products.

​
Step 4 — Customize the widget

Go to Widget in the Cartally panel sidebar to set:
  • Search bar position and appearance
  • Colors, fonts, and language
  • Result layout (grid or list)
  • Custom CSS overrides
See Customize Style for full details.

​
Features

  • Magento 2.x REST API — native integration via /rest/V1/ endpoints
  • Multi-store views — each store view is synced as a separate language
  • Multi-currency — all active currencies are indexed for accurate price filtering
  • Configurable products — variants are split by color for better search results
  • Automatic sync — products are periodically re-synced to keep your search index up to date

​
Troubleshooting

The Access Token is invalid or expired. Go to System → Integrations in Magento Admin, find the Cartally integration, and click Reauthorize. Copy the new token and update it in the Cartally panel.
Verify that the integration has Catalog → Products read permission. Also check that your products have Status = Enabled and Visibility set to “Catalog”, “Search”, or “Catalog, Search” (products with visibility “Not Visible Individually” are skipped).
Ensure you have multiple Store Views configured in Stores → All Stores, each with a different locale. Cartally detects languages from the store view locale settings (e.g., en_US, pl_PL).
Cartally constructs image URLs using your store’s base URL and the media gallery paths. Make sure your Stores → Configuration → Web → Base URLs are correct and that product images are properly uploaded in the catalog.