This guide is for the person who manages the EE installation and web server. Complete it on a staging copy first. This build is for integration evaluation; production release acceptance is not yet complete.

1. Check requirements

The installer checks the PHP, EE, CartThrob, and encryption requirements. A successful install does not certify your payment gateway or every custom CartThrob extension. Test your actual store configuration.

Back up the database, add-on files, templates, and EE encryption configuration before installing or updating. Preserve the encryption key with the backup: encrypted carts, checkouts, signing keys, credentials, and queued notifications depend on it. Changing it independently of the database can make stored data unusable.

2. Copy and install

Copy the complete ct_ai directory to:

YOUR_EE_ROOT/system/user/addons/ct_ai/

The folder must be named ct_ai, not ct_ai/ct_ai. Keep the runtime directories, vendor-prefixed, resources, and the root README/customer guides. resources contains required protocol schemas, currency data, and templates. Do not strip it from the package. A complete distribution already includes its prefixed runtime dependencies; production installation does not require running Composer.

Development reports in docs/, tests, and development tools are not installation prerequisites. Never install the test/spike add-on on a customer site.

In the EE control panel, open Add-ons, locate CartThrob AI, and install it. Alternatively, run this from the EE root (the directory containing system/):

php system/ee/eecli.php addons:install --addon=ct_ai

Installation creates the add-on tables, registers hooks and the browser handoff Action, seeds settings, and generates encrypted initial EdDSA and ES256 signing keys for existing EE sites. You do not need to generate initial signing keys manually. Buyer REST and browser handoff start disabled.

For an already-installed add-on, use Update, not a fresh install. See the update section below.

3. Set the public address

In system/user/config/config.php, configure the public address of the store:

$config['ct_ai_public_origin'] = 'https://shop.example.com';
$config['ct_ai_base_path'] = '/ucp';

Replace shop.example.com with the actual store host. The origin includes only HTTPS, host, and optional port: no /index.php, subdirectory, query, or fragment. /ucp is the API routing prefix, not a physical folder.

Keep the control panel's Base path setting equal to ct_ai_base_path. A mismatch makes the API return 503. Use the default unless there is a concrete routing conflict. For a subdirectory installation, have the host adapt rewrites to the actual EE front controller while preserving the public API paths.

For Multi-Site Manager, configure the correct origin and base path for each site through the site's EE configuration. Maps, settings, credentials, and jobs are site-scoped. Select the correct site in the CP and use its ID in CLI jobs. When adding an MSM site after installation, run the add-on update to seed missing defaults and initial keys.

4. Route requests to EE

The host must route /.well-known/ucp, /ucp/v1/..., and /ucp/continue/... to EE while preserving the original request path, method, body, host, and authorization headers. Keep existing CartThrob/EE routes working.

These are configuration fragments to adapt to your server, not replacements for a complete virtual host.

Nginx

Inside the store's HTTPS server block, retain the existing PHP/FastCGI configuration:

client_max_body_size 2m;
ssl_protocols TLSv1.3;

location ^~ /.well-known/acme-challenge/ {
    try_files $uri =404;
}

location = /.well-known/ucp {
    rewrite ^ /index.php last;
}

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Avoid another /.well-known rule swallowing UCP discovery. Keep certificate renewal challenges reachable.

Apache

With mod_rewrite and the appropriate AllowOverride permissions, use equivalent rules in the document-root .htaccess or Directory configuration:

CGIPassAuth On
RewriteEngine On
RewriteRule ^\.well-known/acme-challenge/ - [L]
RewriteRule ^\.well-known/ucp$ index.php [L,QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L,QSA]

In the HTTPS virtual host:

SSLProtocol -all +TLSv1.3
LimitRequestBody 2097152

CGIPassAuth On preserves bearer credentials when using PHP-FPM. If .htaccess cannot set it, the host must set it in the Directory configuration.

Proxies, CDNs, and sessions

If HTTPS terminates at a trusted proxy, configure the server to supply the real HTTPS state and peer address to PHP. The add-on does not trust arbitrary X-Forwarded-* headers. Preserve the configured public authority.

Do not cache cart/checkout API responses, handoff redirects, handoff Action responses, or the native checkout page. Discovery may be cached according to its response headers. Do not let page optimization tools replace API JSON with HTML, challenges, or redirects.

Handoff URLs contain bearer tokens. Redact /ucp/continue/ token paths and the handoff Action's t query value from access/analytics logs. Keep tokens out of support tickets. The shopper's browser must be able to establish the normal secure EE/CartThrob session.

5. Prepare the native checkout

First complete the CartThrob store checklist. The add-on does not generate a storefront, checkout form, payment gateway, order channel, or customer order page.

In the existing checkout template, put this immediately above the native CartThrob payment form:

{exp:ct_ai:handoff_notice}

Keep the store's working {exp:cartthrob:checkout_form} and its required fields and return handling. The notice explains the agent-prepared cart and changed-price information when applicable; it outputs nothing without a notice. Do not cache this portion of the checkout page.

Ensure CartThrob saves orders to its configured native order channel. Create or verify a shopper-authorized order page before setting the order permalink pattern. Knowing a numeric order ID must not grant access to another customer's order.

Then complete catalog mapping and checkout settings. Leave Development catalog reads at Require platform profile. No ct_ai_development setting is needed for a normal installation.

6. Set up background jobs

Run commands from the EE root with the same supported PHP/extensions and configuration used by the website. Replace site ID 1 with the correct MSM site ID.

Refresh the catalog

php system/ee/eecli.php ct_ai:reindex --site-id=1 --batch-size=100

This processes all batches and prints one JSON line per batch with counts and, for every entry that could not be indexed, its ID and the reason. When any entry failed, the command exits non-zero and finishes with a plain-text summary, one line per failed entry, so a scheduler log shows what to fix. Batch size accepts 1–500. Schedule a full rebuild at an interval appropriate to scheduled publication/expiration and imports; hourly is a starting point to evaluate for your store. Normal EE entry saves trigger updates, but direct SQL imports and time-based visibility need periodic reindexing.

For an interrupted large job, the JSON output supplies a resume cursor:

php system/ee/eecli.php ct_ai:reindex --site-id=1 --batch-size=100 --after=123 --one-batch

Use the actual cursor, not 123. --one-batch processes only one batch; omit it to continue through the remaining entries.

Deliver order notifications

php system/ee/eecli.php ct_ai:outbox --site=1 --limit=25

Schedule approximately once a minute for each participating site. The limit accepts 1–100. The add-on does not install a scheduler. Configure your host's scheduler with the EE root as its working directory and capture command output/errors in a protected log. Monitor failures instead of discarding output.

The worker needs the configured public origin, active EdDSA signing key, and outbound public HTTPS/DNS access. It rejects private/loopback webhook destinations. Initial keys are installed automatically; do not rotate them as a routine response to delivery failures.

7. Verify the installation

1. Open Add-ons → CartThrob AI using an EE account with add-on access and administration permissions. Confirm the expected CT product channels are listed.
2. Preview and index a known product, enable Buyer REST, and run Catalog health. Resolve public DNS, certificate, TLS, routing, and response-header warnings.
3. Request discovery without a platform credential:

   curl -i 'https://shop.example.com/.well-known/ucp'
   

   Expect JSON, public signing keys, an ETag, and the enabled capabilities. A storefront HTML page means routing is wrong. Disabled Buyer REST means shopping capabilities are not advertised.

4. Have the integration developer run the platform connection checks. A placeholder platform.example profile will not work: it must be a real, valid public platform profile.
5. With a gateway in its supported test mode, complete a purchase from catalog search through the shopper's native checkout. Verify selected options, coupon, shipping, tax, payment status, saved native order, linked API checkout, and signed notification receipt. Test declines and expired handoff links too.

Do not treat discovery success alone as checkout acceptance. Real payment gateway and platform acceptance remain necessary for your installation.

Updating, disabling, and removing

Update: back up files, database, and encryption configuration; replace the add-on with the complete new package; then use EE's add-on update or:

php system/ee/eecli.php addons:update --addon=ct_ai

Run even when replacing files at the same version so hook registration and missing defaults can be repaired. Updates preserve existing signing keys rather than rotating them. Recheck health and a test purchase; rebuild the catalog after mapping or variant-cap changes.

Disable new agent checkout: set Browser checkout handoff to Disabled. Catalog can remain available with Buyer REST enabled. Disable Buyer REST as well to stop buyer API access. Previously attributed native payments and already-queued notifications can still synchronize; keep the worker running to drain outstanding events.

Remove permanently: uninstalling deletes the add-on's agent data and audit history across all sites. Stop and reconcile outstanding work, preserve required records, and take backups first. The browser uninstall path requires an additional acknowledgment; CLI uninstall is destructive without that extra browser acknowledgment. Removing files is not the same as a database uninstall. Do not uninstall merely to update or troubleshoot.