> ## 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.
# Magento
> Connect your Magento 2 store to Cartally using an Integration Access Token.
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:
```html theme={null}
```
4. Save the block.
5. Go to **Content → Widgets → Add Widget**.
6. Choose **CMS Static Block** as the type and your theme.
7. In **Layout Updates**, set **Display on** to "All Pages" and **Container** to "Before Body End".
8. In **Widget Options**, select the block you created.
9. 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`:
```xml theme={null}
```
After adding, clear the cache:
```bash theme={null}
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](https://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](/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.