Personal Shopper AI: Official Documentation

Personal Shopper AI adds a conversational shopping assistant to WooCommerce. Shoppers can describe what they need, browse matching products, compare specifications, assemble bundles, change individual items, and add recommendations to their cart through interactive product cards.

This guide covers installation, configuration, catalog preparation, analytics, testing, privacy, and troubleshooting.

1. Requirements

Before installing Personal Shopper AI, confirm that your site has:

  • WordPress 6.0 or newer
  • WooCommerce 8.0 or newer
  • PHP 7.4 or newer
  • HTTPS on production sites
  • An active Personal Shopper AI license
  • An OpenAI API account with API billing enabled
  • Published WooCommerce products with valid prices and stock information

Personal Shopper AI will not start if WooCommerce is inactive. The storefront widget and chat service also require an active plugin license.

2. Installation and License Activation

Install the plugin

  1. Download the Personal Shopper AI plugin ZIP from your account at getpsai.com.
  2. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
  3. Select the plugin ZIP and click Install Now.
  4. Click Activate Plugin.

Activate your license

  1. Go to Plugins > Installed Plugins.
  2. Find Personal Shopper AI for WooCommerce.
  3. Click Manage License.
  4. Enter the license key provided with your purchase.
  5. Activate the license.

An active license enables the storefront widget, the chat endpoint, and eligible automatic updates. If the license expires or is deactivated, the assistant is disabled, but your WooCommerce products, orders, and other store data remain intact.

3. Connect OpenAI

Personal Shopper AI uses a Bring Your Own Key model. Your WordPress site communicates directly with OpenAI, and OpenAI bills your account for actual API usage.

The plugin currently uses gpt-4o-mini.

Create an API key

  1. Sign in to the OpenAI Developer Platform.
  2. Open the billing section and enable API billing.
  3. Consider setting a monthly budget and usage alerts.
  4. Open API Keys and create a new secret key.
  5. Copy the key when it is displayed. OpenAI may not show it again.

OpenAI billing requirements and pricing can change. Refer to OpenAI's current pricing and account documentation instead of relying on a fixed minimum balance.

Connect the plugin

  1. In WordPress, go to WooCommerce > Personal Shopper AI.
  2. Open AI Brain & Persona.
  3. Paste your API key into the OpenAI API Key field.
  4. Save the settings.
  5. Click Test Key Connection.

The key is stored as a WordPress option and used by the server. It is not included in storefront JavaScript or exposed to shoppers. Protect WordPress administrator accounts, backups, and database access as you would any other system containing credentials.

Understand OpenAI costs

Usage depends on:

  • Store traffic
  • Conversation length
  • The amount of recent context sent with a request
  • Product searches and validation steps
  • Catalog Test Engine activity
  • OpenAI's current model pricing

The plugin limits recent message history, message size, tool loops, and request frequency, but you should still monitor the OpenAI usage dashboard and configure billing alerts.

4. Configure the Assistant

Open WooCommerce > Personal Shopper AI > AI Brain & Persona.

Assistant Internal Name

Choose the name the assistant uses as part of its persona, such as Alex, Mia, or Store Specialist.

Store Context and System Rules

Store Context is the assistant's operating brief. It is not conventional model training and does not modify the underlying OpenAI model. It provides instructions with each conversation.

A useful Store Context should explain:

  • What the store sells
  • Who the store serves
  • The desired tone and terminology
  • Important product-selection priorities
  • Shipping, warranty, or sales policies that affect recommendations
  • Statements or claims the assistant must avoid
  • When the shopper should contact a professional or store representative

Do not place API keys, passwords, customer information, private business data, or other secrets in this field.

Example: construction supply store

You are a practical construction supply specialist serving contractors and experienced DIY customers. Prioritize in-stock products, clear material specifications, and value over marketing language. Recommend required safety equipment when relevant, but do not claim that a product satisfies a building code or job-site safety requirement unless that information is explicitly present in the catalog. Ask a clarifying question when dimensions, voltage, load rating, or material compatibility are missing.

Example: fashion store

You are a polished personal stylist. Help shoppers assemble coordinated outfits within their budget. Use the product catalog as the source of truth for sizes, colors, materials, prices, and availability. Do not promise fit. Encourage shoppers to consult the store's size chart when measurements are important.

5. Customize the Widget

Open WooCommerce > Personal Shopper AI > Widget Branding.

Available settings

  • Widget Header Title: Main title displayed in the chat header.
  • Widget Header Tagline: Supporting text beneath the title.
  • Initial Welcome Greeting: First message shown before the shopper types.
  • Chat Input Placeholder: Hint displayed in the message field.
  • Starter Prompts: Up to four suggestions, entered one per line.
  • Accent Color: Brand color used by the widget.
  • Launcher Position: Left or right side of the storefront.
  • Initial Widget Width: Desktop width from 340 to 480 pixels.
  • Launcher Style: Full or compact launcher.

Review the widget on desktop and mobile after changing branding. Theme styles, accessibility plugins, script optimization, and custom CSS can affect its appearance.

6. Prepare the WooCommerce Catalog

Recommendation quality depends heavily on catalog quality. The assistant cannot reliably infer missing specifications from a product name or marketing description.

For best results, maintain:

  • Clear, specific product names
  • Complete short and full descriptions
  • Accurate product categories and tags
  • Consistent WooCommerce attribute names
  • Exact attribute values with units where appropriate
  • Current regular or sale prices
  • Correct stock status and stock quantities
  • Useful product images
  • Complete variation data for variable products

The assistant searches published products that have a positive price and are currently in stock. Missing prices, draft status, or out-of-stock status can prevent a product from appearing.

Use consistent attributes

Compatibility and comparison depend on structured attributes. Use the same field names and value formats across related products.

Good examples include:

  • Voltage: 18 V
  • Battery Platform: Brand X 18 V
  • Connector Type: USB-C
  • Material: Stainless Steel
  • Maximum Load: 250 lb
  • Width: 36 in
  • Supported Models: Series A, Series B

Avoid mixing formats such as 18V, 18 volts, and Eighteen Volt when they mean the same thing. Do not rely on product titles alone to establish compatibility.

Product types

Simple products are supported throughout product discovery and interactive cards. Variable products can be included where variation data is available, especially in the Bundle Builder. Test variable-product behavior with your actual variation, price, and stock configuration before launch.

Grouped, external, subscription, booking, or heavily customized product types should be tested on staging because their cart behavior may depend on another plugin.

7. Shopping Workflows and Generative UI

Personal Shopper AI combines conversational responses with interactive interfaces.

Used for browsing recommendations. It presents product images, names, prices, ratings, and add-to-cart actions.

Example request:

Show me waterproof hiking jackets under $150.

Comparison Table

Used for side-by-side analysis. It compares structured specifications available in WooCommerce.

Example request:

Compare these cordless drills by voltage, chuck size, weight, and price.

An incomplete catalog produces an incomplete comparison. The assistant should not be expected to supply specifications that are absent from WooCommerce.

Bundle Builder

Used for kits, outfits, routines, systems, and groups of products commonly purchased together. Shoppers can review selected items, choose supported variations, and add multiple products to the cart.

Example request:

Build a beginner woodworking kit for under $500.

Follow-up changes

Shoppers can refine an active selection using requests such as:

Replace the drill with a cheaper option.
Remove anything made from leather.
Keep the jacket but rebalance the outfit under $300.
Show me a premium alternative to the monitor.

The plugin attempts to preserve unaffected items, enforce exclusions, and keep the revised bundle within the requested budget.

8. Complete Builds and Compatibility

When a shopper requests a complete working system, the plugin independently plans the minimum required product roles and validates the proposed selection before presenting it as complete.

A complete build is blocked when:

  • A required product role is unavailable
  • A required item cannot fit within the budget
  • Structured compatibility evidence is missing or ambiguous
  • Catalog attributes prove that products conflict
  • Validation cannot establish that the products work together

This fail-closed behavior is intentional. The assistant should not present a partial or unverified selection as a complete working system.

Store owner responsibilities

Stores that sell compatibility-dependent products must maintain accurate, consistent metadata for technical, physical, dimensional, electrical, chemical, medical, or other interoperability requirements.

Personal Shopper AI does not independently certify:

  • Electrical or engineering safety
  • Building-code compliance
  • Medical suitability
  • Legal or regulatory compliance
  • Product fit when measurements are missing
  • Manufacturer warranties
  • Installation requirements

Interactive recommendations do not replace professional advice for regulated or safety-critical decisions.

9. Cart Actions and Revenue Attribution

When a shopper adds a product through an AI-generated card, the plugin adds an attribution marker to the WooCommerce cart item. That marker is preserved on the order line item during checkout.

The Analytics & ROI dashboard uses those markers to identify:

  • Orders containing AI-attributed products
  • Revenue from AI-attributed line items
  • The interface that produced the cart action

Only line items added through Personal Shopper AI are attributed. An entire order is not credited to the assistant simply because one attributed item appears in it.

Attribution reports are directional commerce analytics. Use WooCommerce reports, payment records, and accounting systems for authoritative financial reporting.

10. Analytics and ROI

Open WooCommerce > Personal Shopper AI > Analytics & ROI.

The dashboard includes:

  • Chat Sessions: Unique anonymous shopping sessions observed by the assistant.
  • Chat Turns: Shopper and assistant interactions.
  • Card Renders: Product Carousel, Comparison Table, and Bundle Builder displays.
  • Attributed Orders: Orders containing at least one AI-attributed line item.
  • Attributed Revenue: Revenue from attributed line items.
  • Conversion Rate: Relationship between tracked sessions and attributed orders.
  • Average Turns per Session: Average conversational depth.

Analytics are stored locally in WordPress. Numbers may differ from other analytics platforms because browser behavior, blocked requests, cart changes, refunds, and attribution rules differ between systems.

11. Catalog Test Engine

The Catalog Test Engine creates synthetic WooCommerce inventory for development, demonstrations, and quality assurance. Use it on a staging or development site whenever possible.

What it generates

Depending on the store concept, generated products may include:

  • Product names and descriptions
  • Categories
  • Budget, mid-range, and premium pricing
  • Dimensions and weight
  • Structured attributes
  • Compatibility groups and related product roles
  • Stock quantities
  • Synthetic reviews
  • Simple and variable products
  • Placeholder images

Generated catalog information is synthetic. Do not treat generated compatibility, safety, pricing, review, or product data as authoritative commercial information.

Generate test inventory

  1. Open WooCommerce > Personal Shopper AI > Catalog Test Engine.
  2. Enter a focused store concept or industry.
  3. Choose a target from 1 to 1,000 products.
  4. Click Seed Store Inventory.
  5. Keep the page open while generation is running.

Example store concept:

Gaming PC components, compatible computer parts, custom PC hardware, peripherals, networking equipment, cables, replacement parts, cooling, storage, displays, gaming furniture, and accessories

The seeder creates one shared, domain-neutral role and compatibility blueprint for the run. Product batches reuse that blueprint so related products receive consistent compatibility evidence.

Performance and retries

  • Products are generated in batches of five.
  • Up to three batches run concurrently.
  • Temporary gateway and network failures are retried up to four attempts.
  • Run and batch identifiers prevent a completed timed-out batch from being duplicated.
  • A 1,000-product run creates 200 batches and can take a considerable amount of time.
  • Large runs can consume significant OpenAI API usage.

Stopping the browser process cancels requests from the browser, but a PHP request already accepted by the server may continue briefly.

Wipe generated inventory

Click Wipe Tagged Test Inventory to remove test products created by the seeder. The wipe process targets inventory carrying the plugin's internal test tag and is designed not to remove ordinary store products.

Wipe test inventory before:

  • Starting a replacement test catalog
  • Moving a staging database into production
  • Deactivating or uninstalling the plugin

Back up the database before running bulk generation or deletion tools.

12. Privacy and Data Processing

Store owners are responsible for evaluating applicable privacy, consent, cookie, and disclosure requirements.

Data sent to OpenAI

The plugin may send the following to OpenAI to generate a response:

  • Shopper messages
  • Recent conversation context
  • Assistant instructions and Store Context
  • Relevant product information and structured specifications

Review OpenAI's current API terms, privacy information, and data-processing options before enabling the assistant.

Data stored in the shopper's browser

The widget uses browser storage for:

  • Recent chat interface state
  • An anonymous shopping-session identifier
  • Active conversational and bundle context

WooCommerce may separately use cookies or browser storage for carts and sessions.

Data stored in WordPress

The plugin stores local engagement analytics and WooCommerce order-item attribution. Shopper chat transcripts are not intended to become permanent CRM records.

Developer telemetry

Remote developer telemetry is disabled by default, and the plugin ships without a configured remote telemetry destination. Private diagnostics are also disabled by default and cannot be enabled through the normal admin interface.

Suggested privacy disclosure

Your privacy policy should explain that:

  • The store uses an AI shopping assistant
  • Messages and relevant catalog data may be processed by OpenAI
  • Anonymous browser storage supports chat and cart context
  • Local analytics measure assistant engagement and attributed purchases
  • WooCommerce uses its own cart and checkout technologies

Have qualified counsel review disclosures for your location and industry.

13. Security and Usage Controls

Personal Shopper AI includes:

  • Server-side OpenAI requests
  • WordPress REST nonce checks
  • WooCommerce-management permission checks for admin tools
  • Anonymous session isolation
  • Input sanitization
  • Bounded conversation history
  • Maximum message lengths
  • Session and network request limits
  • Restricted private diagnostics

Current chat limits include:

  • Up to 20 recent messages sent with a request
  • Up to 4,000 characters per message after sanitization
  • Up to 8 chat requests per minute per session
  • Up to 30 chat requests per minute per network address

These controls reduce abuse but do not replace normal WordPress security. Keep WordPress, WooCommerce, themes, and plugins updated; require strong administrator authentication; use HTTPS; and maintain tested backups.

14. Launch Checklist

Before enabling the assistant for shoppers, verify:

  • WooCommerce is active.
  • The Personal Shopper AI license is active.
  • The OpenAI connection test passes.
  • OpenAI billing limits and alerts are configured.
  • HTTPS is enabled.
  • Products are published, priced, and in stock.
  • Categories and attributes use consistent names and values.
  • Compatibility-dependent products have complete structured evidence.
  • Store Context contains accurate instructions and no secrets.
  • Widget text and branding have been reviewed.
  • Starter prompts produce useful results.
  • Browse, compare, bundle, swap, and budget workflows have been tested.
  • Variable products and cart actions work with the active theme.
  • Mobile and keyboard behavior have been tested.
  • Page, server, and CDN caches have been cleared.
  • Privacy and cookie notices have been updated.
  • Analytics attribution has been tested through a staging checkout.

15. Troubleshooting

The widget is not visible

  1. Confirm WooCommerce is active.
  2. Confirm the plugin license is active.
  3. Confirm the OpenAI key has been saved.
  4. Clear WordPress, host, and CDN caches.
  5. Disable script optimization temporarily and retest.
  6. Check the browser console for JavaScript errors.
  7. Confirm security software is not blocking the plugin's REST routes.

The OpenAI connection test fails

  1. Confirm the API key is current and copied completely.
  2. Confirm API billing is active in the OpenAI account.
  3. Check OpenAI usage limits and service status.
  4. Confirm the host permits outbound HTTPS requests to OpenAI.
  5. Generate a replacement API key if necessary.

No products are returned

Check that matching products are:

  • Published
  • Positively priced
  • In stock
  • Assigned to useful categories
  • Described with relevant product terms
  • Populated with consistent attributes

Try a broader shopper request to determine whether the issue is catalog coverage or overly narrow criteria.

Compatibility cannot be verified

The assistant found candidate products but could not prove they work together. Review the required products and add explicit, consistent compatibility attributes. Do not simply add compatibility claims to descriptions; use structured WooCommerce attributes.

A shopping session expired

Refresh the page to obtain a current WordPress REST nonce and shopping-session identifier. If the problem returns, clear page and CDN caches and ensure long-lived cached pages are not serving expired nonces.

A rate-limit message appears

Wait at least one minute before trying again. Repeated automated requests, shared network addresses, or security tools can trigger session or network limits.

Seeder HTTP 502, 503, or 504 errors

The seeder automatically retries temporary gateway failures. Keep the page open. A recovered batch may be labeled as recovered after a timeout.

If all attempts fail:

  1. Review host PHP and web-server logs.
  2. Confirm PHP workers and memory are available.
  3. Check OpenAI service status and account limits.
  4. Retry with a smaller target catalog.
  5. Ask the host to review gateway and PHP execution timeouts.

Use Wipe Tagged Test Inventory before starting over if you do not want to keep the partial catalog.

Analytics show no attributed revenue

Only products added through AI-generated cards receive attribution. Products added through ordinary product pages, other plugins, imports, or manual order edits are not automatically attributed.

The storefront still loads an older version

  1. Confirm the current plugin version under Plugins.
  2. Clear WordPress, host, CDN, and browser caches.
  3. Hard-refresh the storefront.
  4. Confirm script optimization is not serving an obsolete generated bundle.

16. Updates and Backups

An active license provides eligible update notifications through WordPress. Before updating:

  1. Back up the WordPress database and files.
  2. Test major changes on staging.
  3. Install the update through WordPress or replace the plugin with the supplied ZIP.
  4. Clear site, CDN, and browser caches.
  5. Retest the widget, cart, checkout, and analytics attribution.

Updating plugin files does not automatically rewrite existing WooCommerce product metadata. Catalog improvements that require new attributes must be applied to the products themselves or generated again on a test site.

17. Deactivation and Uninstallation

Deactivation stops the plugin without intentionally removing its settings or ordinary WooCommerce data.

Before uninstalling:

  1. Back up the site.
  2. Open the Catalog Test Engine.
  3. Click Wipe Tagged Test Inventory if test products were generated.
  4. Confirm the generated products were removed.
  5. Uninstall the plugin from WordPress.

The uninstall routine removes plugin settings, the stored OpenAI key, local plugin analytics, telemetry settings, plugin transients, and plugin database tables where present. Ordinary WooCommerce products, orders, and customer records are not intended to be removed.

18. Frequently Asked Questions

Can Personal Shopper AI work with any type of store?

The architecture is domain-neutral. Results still depend on the quality and completeness of each store's catalog and attributes.

Does it guarantee that products are compatible?

No general guarantee is possible. For complete working systems, the plugin requires explicit catalog evidence and blocks the build when compatibility cannot be verified. Store owners remain responsible for product-data accuracy and professional or regulated advice.

Does the plugin expose my OpenAI key?

The key is used by server-side WordPress requests and is not intentionally sent to storefront JavaScript or shoppers.

Does it recommend out-of-stock products?

Catalog discovery and rendered results are filtered for current stock availability.

Can shoppers compare products?

Yes. Comparison quality depends on consistent WooCommerce specifications and attributes.

Can shoppers modify a bundle?

Yes. They can request replacements, cheaper alternatives, exclusions, or a revised total budget.

Is chat history permanent?

No. Recent conversation state is maintained for the active shopping experience and is not intended as permanent customer memory or a CRM record.

Does the plugin use cookies?

The widget uses browser storage for session and interface state. WooCommerce may use cookies and storage for cart functionality. Document these technologies according to your legal obligations.

Is the analytics dashboard an accounting report?

No. It provides directional engagement and assisted-revenue analytics. Use WooCommerce, payment, and accounting records for authoritative reporting.

What should I provide when requesting support?

Include:

  • WordPress, WooCommerce, PHP, theme, and plugin versions
  • The exact shopper request
  • The expected and actual result
  • Whether the issue occurs for all shoppers
  • Relevant browser-console and server-log errors
  • Any caching, security, cart, checkout, or product-type plugins involved

Never send an OpenAI API key, license key, password, or customer data in a support request.