README

Turn your Magento storefront into a conversion machine. IDEA89 adds an AI-powered shopping assistant that answers product questions, recommends what to buy, and surfaces promotions — in your brand voice.

5-minute install. No theme changes. No dev work.

What it does

Feature	Description
Smart product recommendations	AI understands natural language queries like "something waterproof under 100 pounds" and finds the right products from your catalogue
Real-time catalogue sync	Products, variants, prices, stock levels, and reviews are synced automatically. Out-of-stock items are never recommended
Brand voice	Configure your assistant's name, tone, and store context. It answers like a member of your team
Promotion awareness	Active cart price rules are synced so the assistant can surface relevant discounts
In-chat order tracking (new in v1.1.1)	When a shopper asks "where is my order?" the assistant surfaces a compact order card right in the chat with status, items, and a carrier tracking link. Logged-in customers see their last 3 orders; guests verify with order number + email
Store Locator (new in v1.1.0)	Physical showroom finder with map, postcode search, hours, photos, and directions — in chat and on a dedicated `/store-finder` page (URL configurable)
Configurable checkout (new in v1.3.0)	Choose how far the assistant carries a shopper: send them to your cart page, hand off to your checkout, open your checkout inside the chat panel, or have the assistant collect delivery details and place the order itself (beta). Express handoff is the default and never touches your checkout
Agentic Commerce (new in v1.3.0)	Publish your catalogue so AI shopping agents such as ChatGPT can find your products, off by default
Built-in analytics	Track conversations, conversion rates, and top queries from the merchant dashboard
GDPR-ready	EU-hosted, no customer data used for AI training, PII redaction before model calls

How it works

Install the module via Composer
Enter your API key from the IDEA89 dashboard
The widget appears on your storefront immediately
Products sync automatically — the assistant is ready to sell

Your catalogue is indexed with AI embeddings for semantic search. When a shopper asks a question, the assistant searches your products, checks stock, and responds with relevant recommendations — complete with product cards, prices, and add-to-cart buttons.

Requirements

Magento 2.4.6 or later (Open Source, Adobe Commerce, or Adobe Commerce Cloud)
PHP 8.1, 8.2, 8.3, 8.4, or 8.5 — practically, whichever your Magento install supports:

Magento PHP range

2.4.6 8.1, 8.2

2.4.7 8.1, 8.2, 8.3

2.4.8 8.2, 8.3, 8.4

2.4.9 8.4, 8.5 (8.3 upgrade-only)
An IDEA89 account — start your free trial

Magento	PHP range
2.4.6	8.1, 8.2
2.4.7	8.1, 8.2, 8.3
2.4.8	8.2, 8.3, 8.4
2.4.9	8.4, 8.5 (8.3 upgrade-only)

Installation

composer require idea89/magento2-assistant
bin/magento module:enable Idea89_Assistant
bin/magento setup:upgrade
bin/magento cache:flush

That's it. No layout XML changes, no theme overrides, no frontend build step.

Configuration

Navigate to Stores > Configuration > IDEA89 > AI Shopping Assistant in Magento Admin.

General

Setting	Description
Enable Widget	Turn the chat widget on/off
API Key	Your API key from the IDEA89 dashboard (stored encrypted)
Assistant Name	Name shown in the widget header (e.g. "Aria", "Shop Helper")
Store Context	Describe what your store sells so the AI can answer general questions
Test Connection	Verify your API key works
Sync Now	Manually trigger a full catalogue sync

Widget Appearance

Setting	Description
Position	Bottom-right or bottom-left
Brand Colour	Hex code for the widget header (e.g. `#2563eb`)

Content Sync

Choose what gets synced to IDEA89:

Products — names, descriptions, prices, images, attributes, variants, stock, reviews
Categories — so the assistant knows your catalogue structure
CMS Pages — About Us, FAQs, policies — the assistant can answer "what's your return policy?"
Store Info — store name and context description

Checkout Experience (new in v1.3.0)

Settings live under Stores → Configuration → IDEA89 → Checkout Experience. Four options for how far the assistant carries a shopper towards a completed order:

Setting	Default	Notes
Assistant Checkout Mode	Express handoff	"Off" sends shoppers to your cart page. "Express handoff" shows a basket summary in chat with one button to your checkout page; never touches your checkout itself. "Checkout in chat" frames your own Magento checkout inside the assistant panel. "Native checkout (beta)" has the assistant collect delivery details and place the order itself
Cart URL Path	`/checkout/cart/`	Only needed if an extension has moved your cart page
Checkout URL Path	`/checkout/`	Only needed if a one-step-checkout extension uses its own path. Shown for Express handoff and Checkout in chat
Test Checkout Panel	n/a	Pre-flight check for Checkout in chat: flags Hyvä Checkout, one-step-checkout extensions, redirect-based payment methods, guest checkout being off, and reCAPTCHA on checkout
Pinned Checkout Bar	Yes	Full-width "Checkout, N items, total" bar above the chat box whenever the basket has items
Payment Methods the Assistant May Use	(none selected)	Native checkout only. Empty by default, so no orders are placed until you choose which methods the assistant may use

Native checkout talks to Magento over four same-origin routes under /idea89/checkout (context, address, method, place). The three that change the quote validate Magento's own form key as CSRF protection, and every one of the four is rate-limited per shopper session: order placement is capped at 8 attempts per session per 10 minutes, everything else at 30.

Agentic Commerce (new in v1.3.0)

Also under Checkout Experience, and independent of the checkout mode above. Lets AI shopping agents outside your widget, such as ChatGPT, find, and where a separate transactional module is installed, buy from your store.

Setting	Default	Notes
Let AI agents shop your store	No	Publishes your catalogue to those third parties once turned on
Publish the Product Feed	Yes	Serves your visible catalogue at `/idea89/acp/feed.json` once Agentic Commerce is on. Disabled products, products not visible individually, and products outside the current website are never included
Agent Access Token	(blank)	Optional bearer token for the feed. Leave blank to serve it publicly

IDEA89 never places an order or touches payment on an agent's behalf: the five checkout-session routes under /idea89/acp/checkout_sessions redirect to a separately installed transactional module (currently Magebit's free Agentic Commerce module) when one is present, and decline with a fixed, documented message otherwise. See docs/agentic-commerce-guide.md for the setup guide.

Store Locator (Pro plan and above)

Settings live under Stores → Configuration → IDEA89 → Store Locator. Twelve fields covering page behaviour and content:

Setting	Default	Notes
Enable Store Finder Page	Yes	Master toggle for the locator page and CMS widget
URL Path	`store-finder`	Pick any slug — `showrooms`, `branches`, `find-a-shop`. Save fails with a clear error if it collides with an existing CMS page, product, category, or module
Page Layout	Use dashboard setting	Fullwidth (edge-to-edge map) or Boxed (max-width card)
SEO Page Title + Meta Description	(sensible defaults)	Standard SEO control over the page head
Hero Eyebrow / Title / Subhead	(sensible defaults)	Override the in-page copy without theme edits
Help Section Heading / Body / CTA Label / CTA URL	"Contact us" → `/contact`	The help section below the map

The page also lives as a CMS widget — drop IDEA89 Store Locator into any CMS page or static block from the widget picker.

Locations themselves are managed in the IDEA89 dashboard → Locator. The chat assistant uses them automatically when a shopper asks "where is your nearest store?"

Order Tracking (every plan)

Settings live under Stores → Configuration → IDEA89 → Order Tracking. Five fields:

Setting	Default	Notes
Enable Order Tracking	Yes	Master toggle. When No, the chat assistant won't surface an order card, and the order endpoints respond with `feature_disabled`
Contact Support URL	`/contact`	Where the "Contact support" button on the order card sends shoppers — relative path, absolute URL, or `mailto:`
Contact Support Button Label	"Contact support"	Match your tone — "Talk to us", "Email the team"
Max Recent Orders Shown	3	How many recent orders to show a logged-in customer (1–10)
Show Carrier Tracking Button	Yes	When Yes, surfaces a "Track parcel" button when a carrier tracking link is available

All fields support per-store-view scope. Online-only retailer? Set Enable Order Tracking = No on that store-view and the card never surfaces.

See docs/order-tracking-guide.md for the full guide — privacy model, supported carriers, troubleshooting, and the order-card JSON shape.

Advanced

Setting	Description
API URL	Override for self-hosted or enterprise deployments. Leave blank for default.

How syncing works

Trigger	What happens
Product saved	Changed product is queued and synced within 1 minute
Stock update	Stock changes are synced within 1 minute
Price rule saved	Active promotions are synced immediately
Nightly cron	Full catalogue re-sync as a safety net (configurable)
Manual sync	Click "Sync Now" in admin to push everything immediately

All syncs are idempotent — sending the same product twice is safe and expected.

The widget

The assistant appears as a floating chat widget on your storefront. It includes:

Conversational AI that understands your products
Product cards with images, prices, ratings, and add-to-cart buttons
Promotional banners for active cart price rules
Quick-reply chips for common questions
Mobile-responsive design
Dark/light theme support
No impact on your Magento theme or page speed (loaded asynchronously)

The widget is served from the IDEA89 CDN — no static content is added to your Magento deployment.

Pricing

Plan	Price	Conversations/mo
Free trial	£0 for 14 days (all Pro features)	100 conversations
Starter	£49/mo	1,000
Growth	£149/mo	10,000
Pro	£349/mo	50,000

Save 10% with annual billing. All plans include the full feature set.

Start your free trial — no credit card required.

Uninstalling

bin/magento module:disable Idea89_Assistant
bin/magento setup:upgrade
composer remove idea89/magento2-assistant
bin/magento cache:flush

No database tables are created in your Magento instance. All data is stored on the IDEA89 platform.

Support

Documentation: idea89.com
Email: support@idea89.com
Dashboard: app.idea89.com

License

This module is licensed under the Open Software License 3.0 (OSL-3.0).

Running unit tests

Unit tests run inside a Magento install (they need magento/framework, which is not on public Packagist). From the Magento root:

vendor/bin/phpunit -c app/code/Idea89/Assistant/phpunit.xml.dist

CI runs phpcs --standard=Magento2 and CodeQL only, for the same reason.

Built by 4K Technologies in the UK.

idea89 / magento2-assistant

Package info

Security

Statistics