Concepts
Organizations, stores, publishable keys, conversations, identity levels, actions, knowledge and capabilities, explained once for all of the docs.
Organization and store
An organization is your ShopAssist account. It holds the team, billing, API keys and webhook endpoints. Agencies use one organization for many clients' stores (see agencies and multiple stores).
A store is one storefront: one Shopify shop, one Magento website, one WordPress site (on multisite: one subsite), one PrestaShop shop, or one site connected through feeds or the API. Catalog, conversations and settings always belong to one store.
Publishable key
Each store has a pk_live_… key that the widget uses on your storefront and a pk_test_… key for testing. Publishable keys are public by design; they only identify the store. The widget only works on the domains you allow (see verify your installation). Conversations with a test key are never billed and never execute order actions.
Conversation
A conversation is one chat thread between a shopper and your store. It closes automatically after 24 hours without activity. For billing, a conversation starts when the first AI reply is delivered to a shopper who wrote something; read what is a conversation for the exact rule.
Identity levels
What the assistant may tell a shopper about orders depends on how sure ShopAssist is about who they are:
| Level | How it is reached | What it unlocks |
|---|---|---|
guest | Default | Products, stock, store hours, policies, cart help |
order_lookup | Order number, email and one more factor for one order | Read-only status of that one order |
order_otp | A one-time code sent to the order's email | That order, plus actions you allow for verified guests |
customer | Signed in on your store (verified by your platform or your server) | The customer's orders and the order actions you enable |
Details: orders and identity.
Actions and confirmations
The assistant can propose actions such as cancelling an order or starting a return. It never executes them on its own: the shopper confirms on a confirmation card in the widget, and ShopAssist checks the order again with your platform before executing. Cart actions (add to cart, apply a discount code) run in the shopper's browser against your platform.
Knowledge
Your policies, pages, FAQs, crawled URLs and uploaded files form the knowledge base. The assistant answers policy questions from it and cites it. Prices and stock never come from the knowledge base, only from the synced catalog and live platform reads. See knowledge base.
Capabilities
Platforms differ: stock per location, cancellations or returns work differently on Shopify than on PrestaShop. ShopAssist records what your store supports as capabilities and only offers what works. The capability table on each install guide shows them per platform:
| Capability | Shopify | Magento 2 / Adobe Commerce | WooCommerceBeta | PrestaShopBeta | Any store (Generic: script tag, Push API, feeds) |
|---|---|---|---|---|---|
| Catalog freshness | Webhooks plus sweeps | Plugin push | Plugin push | Change ping, then pull | Feed or Push API1 |
| Variants | Yes | Yes | Yes | Yes | Yes |
| Stock per physical store | Yes (native) | Yes (Magento MSI)2 | Yes (stock-locations plugin)3 | Yes (module hook or feed)4 | Yes (feed or Push API)5 |
| Store opening hours | Shopify metafield | No | Set in the dashboard | platform | platform |
| Signed-in customers | shopify_app_proxy | plugin_endpoint | plugin_endpoint | plugin_endpoint | Your server mints a token6 |
| Order status | Yes (last 60 days)7 | Yes (full history) | Yes (full history) | Yes (full history) | Yes (full history)8 |
| Guest order lookup (extra factor) | last name | last name, postcode | postcode | No | last name, postcode |
| Add to cart | Yes | Yes | Yes | Yes | Yes9 |
| Checkout link | permalink | Checkout with the session cart | Checkout link10 | cartlink | template |
| Discount codes | Yes | Yes | Yes | Yes | Yes11 |
| Cancellations | cancel directly, send a request12 | cancel directly, platform self-service, send a request | send a request, cancel directly13 | cancel directly, send a request | send a request, cancel directly14 |
| Returns | platform return, send a request15 | platform return, send a request | send a request | platform return, send a request | send a request, platform return16 |
| Lead sync to the platform | Synced to customers17 | No | No | Newsletter flag | No |
| Billing | Billed by Shopify | Card or invoice (Stripe) | Card or invoice (Stripe) | Card or invoice (Stripe) | Card or invoice (Stripe) |
- Catalog Push API or scheduled feeds (Google Shopping XML, CSV, JSON)
- Needs coec/module-shopassist-inventory and Magento MSI with at least one enabled source.
- Needs Stock Locations for WooCommerce, a meta-key mapping, or a CSV/feed import.
- Needs a module implementing the actionShopAssistLocationStock hook, or an inventory feed.
- Needs a local inventory feed or inventory batches
- Needs identity tokens minted by the merchant's server
- Orders older than 60 days need Shopify's read_all_orders approval.
- Needs the optional Generic RPC endpoint (customer.orders, customer.order, guest lookup)
- Needs ShopAssist.setCartHandler(...) or an add-to-cart URL on the storefront
- WooCommerce 10.0+ checkout links replace the cart; older versions support single products.
- Needs a JavaScript cart handler implementing applyDiscount
- Direct cancellation needs the optional write_orders permission.
- Direct cancellation only for unpaid orders with an offline payment method.
- direct needs the Generic RPC ops orders.cancel.check and orders.cancel.execute
- Return requests need the optional read_returns and write_returns permissions.
- platform needs the Generic RPC op returns.create
- Lead capture needs the optional write_customers permission.
This is the design target per platform. Each connected store reports what it actually supports in your dashboard.
Managed AI and your own key
With managed AI, ShopAssist runs the model on EU infrastructure and bills per conversation in your plan. With your own key (BYOK), your AI provider bills you directly and the Free plan is enough. See choose your AI.
Last updated on