# Concepts

> Organizations, stores, publishable keys, conversations, identity levels, actions, knowledge and capabilities, explained once for all of the docs.

Source: https://shopassist.coec.dk/docs/getting-started/concepts · Updated 2026-10-01

## Organization and store [#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](/docs/team/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 [#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](/docs/install/verify-your-installation)). Conversations with a test key are never billed and never execute order actions.

## Conversation [#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](/docs/billing/what-is-a-conversation) for the exact rule.

## Identity levels [#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](/docs/orders-and-identity/overview).

## Actions and confirmations [#actions]

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 [#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](/docs/knowledge-base/overview).

## Capabilities [#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](/docs/install) shows them per platform:

| Capability | Shopify | Magento 2 / Adobe Commerce | WooCommerce (Beta) | PrestaShop (Beta) | Any store (Generic: script tag, Push API, feeds) |
| --- | --- | --- | --- | --- | --- |
| Catalog freshness | Webhooks plus sweeps | Plugin push | Plugin push | Change ping, then pull | Feed or Push API[1] |
| 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 token[6] |
| 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 | Yes[9] |
| Checkout link | permalink | Checkout with the session cart | Checkout link[10] | cartlink | template |
| Discount codes | Yes | Yes | Yes | Yes | Yes[11] |
| Cancellations | cancel directly, send a request[12] | cancel directly, platform self-service, send a request | send a request, cancel directly[13] | cancel directly, send a request | send a request, cancel directly[14] |
| Returns | platform return, send a request[15] | platform return, send a request | send a request | platform return, send a request | send a request, platform return[16] |
| Lead sync to the platform | Synced to customers[17] | 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) |

- [1] Catalog Push API or scheduled feeds (Google Shopping XML, CSV, JSON)
- [2] Needs coec/module-shopassist-inventory and Magento MSI with at least one enabled source.
- [3] Needs Stock Locations for WooCommerce, a meta-key mapping, or a CSV/feed import.
- [4] Needs a module implementing the actionShopAssistLocationStock hook, or an inventory feed.
- [5] Needs a local inventory feed or inventory batches
- [6] Needs identity tokens minted by the merchant's server
- [7] Orders older than 60 days need Shopify's read_all_orders approval.
- [8] Needs the optional Generic RPC endpoint (customer.orders, customer.order, guest lookup)
- [9] Needs ShopAssist.setCartHandler(...) or an add-to-cart URL on the storefront
- [10] WooCommerce 10.0+ checkout links replace the cart; older versions support single products.
- [11] Needs a JavaScript cart handler implementing applyDiscount
- [12] Direct cancellation needs the optional write_orders permission.
- [13] Direct cancellation only for unpaid orders with an offline payment method.
- [14] direct needs the Generic RPC ops orders.cancel.check and orders.cancel.execute
- [15] Return requests need the optional read_returns and write_returns permissions.
- [16] platform needs the Generic RPC op returns.create
- [17] 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 [#ai]

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](/docs/ai/choose-your-ai).