Skip to content

Connect Shopify

The Shopify tool connects your KonversAI assistant to your Shopify store. You create a custom app in the Shopify Dev Dashboard, install that app on the store, and create a Headless storefront for product search. You then add the tool on the Assistant tools screen in the KonversAI console. Select Settings in the left sidebar, then select AI tools. Once connected, the assistant searches your product catalog, answers questions about a product and its sizes, and looks up a customer’s orders and shipping status. Order and shipping answers need a verified email address from the customer. Product search does not. You can also let a verified customer get a copy of an order invoice by email. That ability is off until you turn on Invoice copies. You can also let a verified customer put one of their own orders on hold before it ships. That ability is off until you turn on Let customers put orders on hold. Orders that follow a product recommendation in the chat carry a KonversAI note in the Shopify admin, and product links from the chat show up in Shopify’s marketing reports. With the read_online_store_pages scope, KonversAI also adds your store pages, such as shipping and returns, and your blog posts to the knowledge base. To let customers chat with the assistant on your store, you also paste the KonversAI chat widget snippet into your Shopify theme. You can show the widget on every page, or only on the pages you choose.

A team member with the View tools permission opens the Assistant tools screen in the KonversAI console. A team member with the Modify tools permission adds, edits, validates and deletes the tool. A Tenant Admin holds both permissions, always. Without View tools, the item AI tools does not appear under Settings in the left sidebar. Ask a Tenant Admin to grant Modify tools on the User permissions screen. In Shopify you need permission to create an app and to install sales channels. To put the chat widget on your store, you also need permission to edit the theme code.

Sign in to the KonversAI console and select your tenant. Select Settings in the left sidebar, then select AI tools. The screen heading is Assistant tools. See Give the assistant a tool for the fields every tool shares, such as Display name and Slug.

The custom app and the store must belong to the same Shopify organization. A connection check fails when they do not. The app needs these four scopes: read_orders, read_all_orders, read_customers and read_products. Add write_orders only if you turn on Invoice copies. Add write_merchant_managed_fulfillment_orders or write_third_party_fulfillment_orders only if you turn on Let customers put orders on hold. Add write_gift_cards only if your case staff will issue gift cards. Add read_online_store_pages so the assistant can answer from your store pages and blog posts; see Add your Shopify store pages to the knowledge base. Add read_markets, read_translations and read_locales so Products copies your prices in up to 10 markets and your product text in up to 10 more languages; without them it copies only your main market and language. See Add products and the product feed. Add no other scopes. read_all_orders is protected. Shopify may ask you to request it. Without it, the assistant sees only the last 60 days of orders.

You also need a Storefront private token from the Headless sales channel. The token is optional, but product search is much better with it. Copy the private token, which starts with shpat_. Do not copy the public storefront token, and do not copy an Admin API token. KonversAI rejects both. Publish your products to the Headless channel. A valid token with no published products sees an empty catalog, and product search returns nothing.

Order and shipping lookups always need a verified email, and answer No verified email found for this conversation. without one. KonversAI includes the Email Verification tool in every workspace, so you do not add it.

Create a custom app in the Shopify Dev Dashboard

Section titled “Create a custom app in the Shopify Dev Dashboard”

Create a custom app in the Shopify Dev Dashboard for the store the Shopify tool should use. Start from the store admin: select Settings, then Apps, then Develop apps. The pictures below show a Norwegian admin, so each caption also gives the Norwegian button name. The app is not embedded in the Shopify admin. You release one version, then copy the Client ID and the Client secret.

  1. In the Shopify admin, select Settings, then Apps. Select Develop apps.

    The Apps page in the Shopify admin, with Apps selected in the settings sidebar and Develop apps highlighted.

    Apps. Select Develop apps. In a Norwegian admin the button reads Utvikle apper.

  2. Select Create apps in Dev Dashboard.

    The App development page in the Shopify admin, with Create apps in Dev Dashboard highlighted.

    Select Create apps in Dev Dashboard. In a Norwegian admin the button reads Lag apper i Dev Dashboard.

  3. In the Dev Dashboard, on Apps, select Create app.

    The Apps list in the Shopify Dev Dashboard, with Create app highlighted in the top right.

    In the Dev Dashboard, select Create app. In a Norwegian admin the button reads Opprett app.

  4. Under Start from Dev Dashboard, type a name in App name, then select Create app. Leave Start with Shopify CLI unused.

    The Create an app page in the Shopify Dev Dashboard, with the app name field and Create app highlighted under Start from Dev Dashboard.

    Under Start from Dev Dashboard, type an app name, then select Create app.

  5. Leave the app URL and the API version as Shopify fills them in. Scroll to API access.

  6. In Scopes, paste read_orders,read_all_orders,read_customers,read_products. To use Invoice copies, also add write_orders. To use Let customers put orders on hold, also add write_merchant_managed_fulfillment_orders, write_third_party_fulfillment_orders, or both. To add your store pages and blog posts to the knowledge base, also add read_online_store_pages. To let your case staff issue gift cards, also add write_gift_cards. To copy prices per market and product text per language to Products, also add read_markets, read_translations and read_locales. Add no other scopes. Shopify says some scopes need permission before a version can include them. Request read_all_orders from the Request access link when Shopify shows it. Without that scope, the assistant sees only the last 60 days of orders. Then select Release.

    The API access section in the Shopify Dev Dashboard, with the four scopes filled in and Release highlighted.

    Scopes, then Release. In a Norwegian admin the labels read Omfang and Frigi.

  7. In Release this new version?, leave Version name and Version message blank. Select Release.

    The Release this new version dialog in the Shopify Dev Dashboard, with Release highlighted.

    Release this new version. In a Norwegian admin the dialog reads Frigi denne nye versjonen?

  8. Shopify opens Versions and marks the new version Active. Select App settings.

    The Versions page in the Shopify Dev Dashboard, with App settings highlighted in the sidebar.

    Versions. Select App settings. In a Norwegian admin the sidebar item reads Appinnstillinger.

  9. Under Credentials, copy the Client ID and the Secret. Keep the Secret private. Paste the Client ID into Client ID on the Shopify tool, and paste the Secret into Client Secret.

    App settings in the Shopify Dev Dashboard, with Client ID and Secret highlighted under Credentials.

    Credentials. Copy Client ID and Secret. In a Norwegian admin the labels read Klient-ID and Hemmelighet.

Install the custom app from the Shopify Dev Dashboard onto the store KonversAI should read. The app and the store must belong to the same Shopify organization.

  1. In the Dev Dashboard, select Overview. Under Installs, select Install app.

    The Overview page in the Shopify Dev Dashboard, with Install app highlighted.

    Overview. Select Install app. In a Norwegian admin the button reads Installer app.

  2. Select your store, then select Install.

  3. If you release a later version with new scopes, install the app again. Approve the new scopes in the Shopify admin. The new scopes apply only after that approval.

Create a Headless storefront in the Shopify admin so you can copy a Storefront private token. Paste that token into Storefront private token on the Shopify tool in the KonversAI console. Select Settings in the left sidebar, then select AI tools, and open the tool.

  1. In the Shopify admin, select Settings, then Channels. Select Shopify App Store.

    The Channels page in Shopify settings, with Channels selected in the sidebar and Shopify App Store highlighted.

    Channels. Select Shopify App Store. In a Norwegian admin the sidebar item reads Kanaler.

  2. Search for Headless, then select Install.

    Shopify App Store search results for Headless, with Install highlighted.

    Install Headless. In a Norwegian admin the button reads Installer.

  3. Under Channels, open Headless. Select Create storefront. In a Norwegian admin the button reads Lag utstillingsvindu.

  4. Open the storefront. Under Manage API access, select Manage beside Storefront API.

    A Headless storefront in the Shopify admin, with Manage highlighted beside Storefront API.

    Manage beside Storefront API. In a Norwegian admin the button reads Behandle.

  5. Copy the Private access token. It starts with shpat_. Do not copy the Public access token.

    The Storefront API page, with the private access token highlighted. The token starts with shpat_.

    Private access token. In a Norwegian admin the label reads Privat tilgangstoken.

  6. On the Storefront API page, under Storefront API permissions, keep unauthenticated_read_product_listings selected. Those permissions apply to every storefront on the Headless channel.

  7. Select Products. Select the products the assistant should find. Open …, then select Include in sales channels.

    The Products page in the Shopify admin. Products is selected, product checkboxes are selected, the ... menu is open, and Include in sales channels is highlighted.

    Products. Select the products, open …, then Include in sales channels. In a Norwegian admin that item reads Inkluder i salgskanaler.

  8. Select Headless, then select Include products.

    The Include products in sales channels dialog, with Headless selected and Include products highlighted.

    Select Headless, then Include products. In a Norwegian admin the button reads Inkluder produkter.

Add the Shopify tool in the KonversAI console

Section titled “Add the Shopify tool in the KonversAI console”

Add the Shopify tool on the Assistant tools screen. Select Settings in the left sidebar, then select AI tools. Use the Client ID, the Client secret, and the shpat_ token you copied in Shopify.

  1. Select + Add tool.
  2. Select Shopify in Tool type. You cannot change the type later.
  3. Type a label in Display name, for example Shopify. KonversAI fills Slug while you type.
  4. Type your instruction in Usage guidance for the AI assistant, for example Use this for product questions, and for order and shipping questions once the customer’s email is verified.
  5. Keep the Enabled checkbox selected.
  6. In the Connection card, fill in:
    • Shop domain — your .myshopify.com address, for example my-store.myshopify.com. Required.
    • API version — the Shopify Admin API quarterly release, for example 2026-01. Keep the value KonversAI fills in unless Shopify asks you to change it.
  7. Select Add secret on Client ID. In the Add secret window, paste the Client ID into Secret value, then select Apply. Do the same for Client Secret.
  8. Add Storefront private token the same way, with the shpat_ token from Headless. You can skip this secret. Product search is worse without it.
  9. Select Test connection. On a new tool, KonversAI saves the tool first, then opens it with the heading Edit tool. A success banner starts with Shopify settings are valid. and then names your shop, your app, the API version, the granted scopes, and whether storefront search is active.
  10. Read any warning under the banner. A warning still lets you continue, but the assistant answers worse until you fix it.
  11. After a successful test, fill in the remaining cards:
    • Kiwi Sizing size guides — turn this on only when your store uses the Kiwi Sizing app for its size guides.
    • Storefront API version — leave blank. Fill it in only when the Storefront API version must differ from API version.
    • Size guide metafield — leave blank unless your store keeps size guides in a product metafield. Then type it as namespace.key, for example custom.size_guide. The metafield can hold text, a size chart image or a link to a store page with the size guide.
    • Store country and Store language — usually leave both blank. On your Shopify store, the chat widget detects the market and language the visitor is browsing by itself. These two fields are only the fallback when no store page is involved, for example an email conversation or a headless storefront. Type the country as an ISO code such as NO and the language as an ISO code such as NB. Fill in both or neither.
    • Invoice copies — leave on Disabled unless verified customers should get order invoices by email. See the next section before you change it.
    • Let customers put orders on hold — off by default. Turn it on only when your staff can act on a held order before it ships. See Let customers put an order on hold before you change it.
    • Tag product links for Shopify reports — on by default. Turn it off only if the chat must not take credit for sales in your marketing reports. See See the orders the chat helped sell.
    • Gift card: highest amount and Gift card: valid for (months) — used when case staff issue gift cards, and only with the write_gift_cards scope. The first caps one card in the shop’s currency. The second sets how long a card works. 0, the default, means it never expires. Check the rules for gift card validity where you sell before you set a short time. A card with an end date shows it in the reply that hands over the code.
  12. Select Save changes. KonversAI shows Validating…, then the same style of banner as Test connection.

Let customers get a copy of an order invoice

Section titled “Let customers get a copy of an order invoice”

Turn on Invoice copies on the Shopify tool so a verified customer can ask the assistant for the invoice for one of their own orders. Shopify then emails the invoice to the customer’s verified email address. The assistant never shows the invoice in the chat, and never sends it to an address typed in the chat. With Invoice copies on Disabled, the assistant does not offer invoices at all.

  1. In Shopify: Open your custom app in the Shopify Dev Dashboard. Add write_orders to Scopes, then select Release.
  2. In Shopify: Select Overview, then Install app. Approve the new scope. The scope applies only after that approval.
  3. In Shopify: In the Shopify admin, select Settings, then Notifications. Open the Order invoice template and check that it reads as an invoice for your store. Shopify uses this template for every copy the assistant sends.
  4. In KonversAI: Select Settings in the left sidebar, then AI tools. Open the Shopify tool.
  5. In KonversAI: In Invoice copies, select Shopify order invoice email.
  6. In KonversAI: Select Save changes. KonversAI checks that the custom app holds write_orders. Without that scope, KonversAI refuses to save.

Turn on Let customers put orders on hold on the Shopify tool so a verified customer can stop one of their own orders before it ships. A customer asks for a hold to change an address, change a size, or cancel the order. The assistant puts the order on hold in Shopify with the customer’s reason as a note, and Shopify notifies your store. A hold changes nothing on the order by itself. Your staff read the reason, make the change, and release the hold in the Shopify admin. With the setting off, the assistant does not offer holds at all.

Shopify decides whether an order can still go on hold. Once your warehouse or fulfillment app has accepted the order, or the order has shipped, Shopify refuses the hold. The assistant then tells the customer it is too late and offers to hand the conversation to your customer service. To give customers time to ask, wait a while between a new order and sending it to your warehouse.

Some warehouses fetch new orders from Shopify on a timer instead of accepting them through Shopify. Shopify cannot tell when such a warehouse already has an order, so it may still accept a hold the warehouse never sees. Ask your warehouse whether it respects Shopify fulfillment holds before you turn this on.

Pick the scope that matches how your orders are shipped:

  • write_merchant_managed_fulfillment_orders — orders you ship from your own locations in Shopify, including a warehouse that reads those orders.
  • write_third_party_fulfillment_orders — orders Shopify assigns to a fulfillment app, such as a third-party warehouse connected as a fulfillment service.
  1. In Shopify: Open your custom app in the Shopify Dev Dashboard. Add one or both scopes to Scopes, then select Release.
  2. In Shopify: Select Overview, then Install app. Approve the new scopes. The scopes apply only after that approval.
  3. In KonversAI: Select Settings in the left sidebar, then AI tools. Open the Shopify tool.
  4. In KonversAI: Turn on Let customers put orders on hold.
  5. In KonversAI: Select Save changes. KonversAI checks that the custom app holds at least one of the two scopes. Without either, KonversAI refuses to save. With only one, KonversAI saves and warns which orders the assistant cannot hold.

The assistant puts an order on hold only for a customer with a verified email address, and only for an order placed with that address. A customer can also release a hold they placed in the chat, so the order ships as it was placed. The assistant never releases a hold your staff placed.

KonversAI shows you which Shopify orders the chat helped sell, in two places in the Shopify admin. Both work once the Shopify tool is connected and the chat widget is on your Shopify store. You turn nothing on for the order note. The report tagging is on by default.

On the order. When the assistant recommends products to a shopper, KonversAI adds a note named KonversAI to that shopper’s cart. Shopify copies the note onto the order. Open the order in the Shopify admin and look under Additional details. The note reads Products recommended in chat (conversation …), with the number of the conversation. The shopper does not see the note. The note applies to orders the shopper places in the same browser tab, on your Shopify store. A headless storefront gets no note.

In Shopify’s marketing reports. With Tag product links for Shopify reports turned on, every product link the assistant gives out carries utm_source=konversai, utm_medium=chat and utm_campaign=product_recommendation. Shopify then counts visits and sales that start from those links under source konversai in its marketing reports. A product link your store already tagged keeps its own tags.

The report tagging has a cost. A shopper who arrived from an ad and then opens a product link from the chat starts a visit with the chat as its source. A report that credits the last source then gives that sale to the chat, not to the ad. The order note does not have this effect.

To turn off the report tagging:

  1. In KonversAI: Select Settings in the left sidebar, then AI tools. Open the Shopify tool.
  2. In KonversAI: Turn off Tag product links for Shopify reports.
  3. In KonversAI: Select Save changes. Product links in new answers carry no tags. The order note stays.

Every time the assistant searches your store for a shopper, KonversAI notes what it searched for, in which market and channel, and which products it showed. To see it:

  1. In KonversAI: Select Products in the left sidebar.
  2. In KonversAI: Select the Insights tab. It shows the products shoppers asked about most, the searches that found nothing, and both split by market and channel. Choose the period, the market or the channel at the top.

The tab needs the View analytics and View tenant settings permissions. A search that found nothing links to its conversation only for someone who may view conversations. Test chats from Test this widget are not counted. Clicks on product links are not counted: they go straight to your store.

A search text is shown only when shoppers in at least two conversations searched for it. A text from one conversation is counted, but not shown: what one person typed stays in their conversation. Products under Asked about most follow the same rule. Select a product there to see the searches that found it.

What is kept, and for how long:

  • The search text is kept for 90 days. After that the text is removed and only the count stays.
  • The whole search is deleted with its conversation, also when old conversations are deleted automatically.
  • When you delete a person (Delete person), or Shopify asks KonversAI to delete a customer’s data, the texts of their searches are removed. The counts stay.
  • A customer’s data export includes their searches.

With Advanced product insights on, the searches that found nothing are also grouped by what the shopper wanted, once a day. Each group says whether you sell it and your store’s search missed it, or you do not sell it. This uses a language model and is billed by use: each search text counts once, the first day it is grouped. Only texts from at least two conversations are sent to the model. The model’s request is kept in KonversAI’s technical log of language model calls, as with the assistant’s own replies. When you turn the feature off, the groups are deleted. Ask KonversAI support to turn it on.

The chat widget is a <script> snippet. Shopify has no app to install for it. Copy the snippet from the KonversAI console, then paste it once into your Shopify theme so the chat button loads on every storefront page. Do this in the published theme, the one customers see.

  1. In the KonversAI console, select Settings in the left sidebar, then select Entry-points. Select the Chat tab.
  2. Add and save a chat entry point, or open a saved one. KonversAI only shows Embed code on a saved entry point.
  3. Open Embed code, then copy the whole snippet. Always copy it from the console. Do not type the key or the address by hand.
  4. In the Shopify admin, select Online Store (Nettbutikk), then Edit Themes (Rediger Tema). On your published theme, open the … menu and select Edit code (Rediger Kode).
  5. Open layout/theme.liquid. Paste the snippet once, just before the closing </body> tag.
  6. Select Save.
  7. Open your live storefront in a new browser tab. The chat button appears in the corner. Check the live storefront, not only the theme editor preview.

The snippet has this shape. The console fills in the real address and key for your workspace.

<script
async
src="https://your-chat-service.example.com/static/widget/bubble.js"
data-tenant-key="YOUR_REFERENCE_KEY"
data-api-base="https://your-chat-service.example.com"
></script>

If your theme has a Custom Liquid section or a footer scripts field, you can paste the snippet there once instead. Do not change data-tenant-key or data-api-base. You do not paste the snippet again when you change the widget colours in Size and Colors on the entry point. For the full install steps and how to test the widget, see Install the widget on your website.

By default the snippet in layout/theme.liquid loads the chat button on every storefront page. To limit the button to some pages, wrap the snippet in a Shopify Liquid condition on the template name. Every Shopify page uses one template, and layout/theme.liquid can read its name. The button then loads only when the condition is true.

  1. Put the widget snippet in your theme first. In the KonversAI console, select Settings, then Entry-points, then the Chat tab. Open Embed code on a saved chat entry point and copy the snippet. In the Shopify admin, select Online Store, then Themes. Open the … menu on your published theme and select Edit code. Open layout/theme.liquid.
  2. Find the snippet you pasted just before the closing </body> tag. Add an {% if %} line above the snippet and an {% endif %} line below it.
  3. Write the condition. This example shows the button on collection pages and product pages only:
{% if template.name == 'collection' or template.name == 'product' %}
<script
async
src="https://your-chat-service.example.com/static/widget/bubble.js"
data-tenant-key="YOUR_REFERENCE_KEY"
data-api-base="https://your-chat-service.example.com"
></script>
{% endif %}
  1. Keep the real src, data-tenant-key and data-api-base values from your own Embed code. Change only the {% if %} line.
  2. Select Save.
  3. Open a page that matches the condition on your live storefront. The chat button appears. Open a page that does not match, such as the home page. The chat button does not appear.

Use these values for template.name:

Page template.name
Home page index
Product page product
Collection page, including the all-products page at /collections/all collection
List of all collections list-collections
Content page, such as About us page
Cart cart
Search results search
Blog blog
Blog post article

Join conditions with or to match several page types. To match one collection only, use {% if template.name == 'collection' and collection.handle == 'summer-sale' %} with your own collection handle. To match one content page only, use {% if template.name == 'page' and page.handle == 'about-us' %} with your own page handle. For the full install steps, see Install the widget on your website.

How do I find a gift card that KonversAI issued?

Section titled “How do I find a gift card that KonversAI issued?”

In Shopify, open Gift cards. Each card KonversAI creates has the note KonversAI gift card, followed by internal case and action IDs, not the case number. If the case shows a needs-checking message, it gives the end of the code to search for. See Work on a case for how staff issue one.

What can the assistant do once Shopify is connected?

Section titled “What can the assistant do once Shopify is connected?”

The Shopify tool gives your KonversAI assistant five abilities. It searches your product catalog, fetches the full description of one product, and fetches a product’s size guide with the sizes that are in stock. It also lists the customer’s five most recent orders, and reports fulfillment and tracking for one order. Add the tool on the Assistant tools screen in the KonversAI console: select Settings in the left sidebar, then select AI tools. The two order abilities need a verified email address; the three product abilities do not. A sixth ability is optional: with Invoice copies turned on, the assistant emails a verified customer the invoice for one of their own orders. A seventh is optional too: with Let customers put orders on hold turned on, the assistant puts a verified customer’s own order on hold before it ships.

Why does the assistant refuse to look up an order?

Section titled “Why does the assistant refuse to look up an order?”

Most often because the conversation has no verified email address. The Shopify tool answers No verified email found for this conversation. and asks the customer to verify. This is deliberate: it stops one customer reading another customer’s orders. KonversAI includes the Email Verification tool in every workspace, so there is nothing to add. The customer needs to complete the verification that the assistant asks for.

Do I really need the Storefront private token?

Section titled “Do I really need the Storefront private token?”

Not to save the tool, but product search is noticeably worse without it. With the token, search runs on the same engine as your store’s own search bar, which ranks results by relevance and copes with a multi-word question. Without it, search falls back to a plain catalog filter that requires every word to match, so a phrase a customer would actually type often returns nothing. The banner says Storefront search: not configured. when the token is missing. Get the token from the Headless channel in the Shopify admin: select Settings, then Channels, select Shopify App Store, and install Headless. Under Channels, open Headless and select Create storefront. In a Norwegian admin that button reads Lag utstillingsvindu. Copy the private token, which starts with shpat_. Paste it into Storefront private token on the Shopify tool in the KonversAI console.

The banner says the Client ID or Client Secret was rejected. What now?

Section titled “The banner says the Client ID or Client Secret was rejected. What now?”

The banner reads Shopify connection check failed: the Client ID or Client Secret was rejected. Verify credentials in the Shopify Dev Dashboard and confirm the app and store belong to the same Shopify organization. Open the app in the Shopify Dev Dashboard, select Settings, and copy the Client ID and the Client secret again from Credentials. Confirm you selected Release, then Install app on that same store. Open the Shopify tool in the KonversAI console — select Settings in the left sidebar, then AI tools — and replace both secrets in the Connection card. Select Test connection. KonversAI never shows a stored secret again, so replace the value rather than trying to read it.

The banner warns that the storefront token was rejected. What did I copy?

Section titled “The banner warns that the storefront token was rejected. What did I copy?”

The warning says The storefront private token was rejected. Shopify has three different tokens and only one works here. Copy the Storefront API private access token, which starts with shpat_. The public storefront token and the Admin API token both fail. In the Shopify admin, open Headless under Channels, open the storefront, and select Manage beside Storefront API. Copy Private access token. Then replace Storefront private token in the Connection card of the Shopify tool in the KonversAI console. Select Settings in the left sidebar, then AI tools, and open the tool. Select Test connection again.

Product search returns nothing, but my products exist. Why?

Section titled “Product search returns nothing, but my products exist. Why?”

Two causes are common. The banner warns The storefront private token is valid but no products are visible to it. when your products are not published to the Headless channel. In the Shopify admin, select Products, select the products, open …, then select Include in sales channels. Select Headless, then select Include products. The second cause is a multi-language store without a Storefront private token. The assistant searches in the visitor’s market and language only with that token. Without it, search uses your store’s primary language and misses products named in another language. Paste the token into Storefront private token on the Shopify tool in the KonversAI console. Open the tool from Settings, then AI tools.

Can a customer get a copy of their invoice from the assistant?

Section titled “Can a customer get a copy of their invoice from the assistant?”

Yes, when Invoice copies on the Shopify tool is set to Shopify order invoice email. The customer asks for the invoice and gives the order number. The assistant first asks the customer to verify their email address. Shopify then emails the invoice to that verified address. The assistant sends invoices only for orders placed with the verified email address. For any other order number, the assistant says it found no such order. The invoice never appears in the chat. Open the tool from Settings, then AI tools, in the KonversAI console. The custom app needs the write_orders scope.

Saving fails with “Invoice copies need the write_orders scope”. What now?

Section titled “Saving fails with “Invoice copies need the write_orders scope”. What now?”

The full message reads Invoice copies need the write_orders scope, which this Shopify app has not been granted. Add it in the Shopify Dev Dashboard and re-install the app, or set Invoice copies to Disabled. Open your custom app in the Shopify Dev Dashboard. Add write_orders to Scopes and select Release. Then select Install app and approve the new scope. Return to the Shopify tool in the KonversAI console and select Save changes again. If you do not want invoice copies, set Invoice copies to Disabled instead. Your Shopify app then needs no write_orders scope.

Shopify sends the invoice with your store’s Order invoice notification template. KonversAI does not write the email. To change the email, open the Shopify admin, select Settings, then Notifications, and edit Order invoice. For an order that is not fully paid, Shopify’s default template also shows a link to pay. Check the template before you turn on Invoice copies on the Shopify tool in the KonversAI console.

Can a customer stop an order from shipping through the assistant?

Section titled “Can a customer stop an order from shipping through the assistant?”

Yes, when Let customers put orders on hold is turned on on the Shopify tool. The customer asks the assistant to stop or change an order and gives the order number. The assistant first asks the customer to verify their email address. The assistant then puts the order on hold in Shopify with the customer’s reason as a note, and Shopify notifies your store. Your staff make the change and release the hold in the Shopify admin. The assistant holds only orders placed with the verified email address. Open the tool from Settings, then AI tools, in the KonversAI console.

Why does the assistant tell a customer it is too late to hold an order?

Section titled “Why does the assistant tell a customer it is too late to hold an order?”

Shopify refused the hold, because the order has shipped or your warehouse or fulfillment app has already accepted the order. KonversAI asks Shopify each time, and does not use a time limit of its own. The assistant tells the customer it could not stop the order and offers to hand the conversation to your customer service. To give customers more time, wait longer between a new order and sending the order to your warehouse. An order where part has shipped goes on hold for the part that has not, and the assistant tells the customer so.

Saving fails with “Putting orders on hold needs the write_merchant_managed_fulfillment_orders or the write_third_party_fulfillment_orders scope”. What now?

Section titled “Saving fails with “Putting orders on hold needs the write_merchant_managed_fulfillment_orders or the write_third_party_fulfillment_orders scope”. What now?”

The full message reads Putting orders on hold needs the write_merchant_managed_fulfillment_orders or the write_third_party_fulfillment_orders scope, and this Shopify app has neither. Add the one that matches how your orders are shipped (or both) in the Shopify Dev Dashboard and re-install the app, or turn off ‘Let customers put orders on hold’. Open your custom app in the Shopify Dev Dashboard. Add write_merchant_managed_fulfillment_orders when you ship from your own locations. Add write_third_party_fulfillment_orders when a fulfillment app ships your orders. Select Release, then Install app, and approve the new scopes. Return to the Shopify tool in the KonversAI console and select Save changes again. A save can also fail with Putting orders on hold needs Shopify API version 2025-01 or later. Then raise API version in the Connection card.

How do I see which Shopify orders the chat helped sell?

Section titled “How do I see which Shopify orders the chat helped sell?”

Open the order in the Shopify admin and look under Additional details. An order placed after the assistant recommended products shows a note named KonversAI that reads Products recommended in chat (conversation …). KonversAI adds the note to the shopper’s cart, and Shopify copies the note onto the order. The note needs the Shopify tool connected and the chat widget on your Shopify store. It covers orders placed in the same browser tab as the chat. For totals, use Shopify’s marketing reports: with Tag product links for Shopify reports turned on, sales from chat product links appear under source konversai.

Will the chat take credit from my ads in Shopify’s reports?

Section titled “Will the chat take credit from my ads in Shopify’s reports?”

It can. With Tag product links for Shopify reports turned on, product links from the chat carry utm_source=konversai. A shopper who arrived from an ad and then opens a chat product link starts a visit with the chat as its source. A report that credits the last source then gives that sale to the chat. To keep your ad reports unchanged, open the Shopify tool in the KonversAI console from Settings, then AI tools. Turn off Tag product links for Shopify reports and select Save changes. The KonversAI note on each order stays.

How do I put the chat widget on my Shopify store?

Section titled “How do I put the chat widget on my Shopify store?”

Copy the snippet from Embed code, then paste it once into your Shopify theme. In the KonversAI console, select Settings in the left sidebar, then Entry-points, then the Chat tab. Open Embed code on a saved chat entry point and copy the whole snippet. In the Shopify admin, select Online Store, then Themes. Open the … menu on your published theme and select Edit code. Open layout/theme.liquid, paste the snippet just before the closing </body> tag, and select Save. Shopify has no app to install for the widget.

The chat button does not show on my Shopify store. What do I check?

Section titled “The chat button does not show on my Shopify store. What do I check?”

Check these four things, in this order. First, open your live storefront, not only the theme editor preview. Second, make sure you edited the published theme. A snippet pasted into a theme that is not published never reaches customers. Third, make sure the snippet in layout/theme.liquid is complete, with both data-tenant-key and data-api-base, and appears once just before </body>. Fourth, hard-refresh the page to skip a cached copy. If the button is still missing, see Install the widget on your website for the browser console warnings to look for.

I changed my Shopify theme and the chat button disappeared. Why?

Section titled “I changed my Shopify theme and the chat button disappeared. Why?”

The snippet lives in your theme code, so a new theme does not have it. Publish the new theme, then paste the snippet again into its layout/theme.liquid. Copy the snippet from Embed code on your chat entry point: select Settings, then Entry-points, then the Chat tab. Shopify also keeps old themes, so the change takes effect only on the theme you publish.

Can I show the chat widget on only some pages of my Shopify store?

Section titled “Can I show the chat widget on only some pages of my Shopify store?”

Yes. In the Shopify admin, select Online Store, then Themes, open the … menu on your published theme, and select Edit code. Open layout/theme.liquid. Wrap the chat widget snippet in a Liquid condition on the template name. For example, add {% if template.name == 'collection' or template.name == 'product' %} above the snippet and {% endif %} below it. The chat button then loads only on collection pages and product pages. Select Save, then check one matching page and one other page on your live storefront. Copy the snippet from Embed code at Settings, then Entry-points, on the Chat tab.

My store sells in several countries. Do I need one widget per market?

Section titled “My store sells in several countries. Do I need one widget per market?”

No. One chat widget covers every market of your Shopify store. The widget reads the market the visitor is browsing from the store page: the country chosen in your store’s country selector, or the domain the visitor is on. The assistant then shows products, prices and links from that market, in that market’s language. A product the market does not sell is not offered. When a visitor switches market during a chat, the next answer follows the new market. This needs the Storefront private token on the Shopify tool, and Shop domain set to your myshopify.com address. Store country and Store language are only a fallback, for conversations with no store page, such as email.

The Shopify tool looks in four places, in order. It first reads the product metafield you named in Size guide metafield, if you set one. It then asks the Kiwi Sizing app, if you turned on Kiwi Sizing size guides. Next it looks for a table in the product description. If Size guide metafield is blank, it finally looks for a product metafield that holds an image or a store page and has “size” or “størrelse” in its name. When it finds none, the assistant says the store publishes no size chart for the product and answers from the list of sizes and their stock instead. Open the tool in the KonversAI console to change this: select Settings in the left sidebar, then AI tools. These fields appear after Test connection succeeds.

Can the assistant read a size chart that is only an image?

Section titled “Can the assistant read a size chart that is only an image?”

Yes. When your store shows a size chart only as a picture, the assistant reads the measurements from the picture and answers from them. It also gives the customer a link to the picture. This works for an image in a product metafield and for a Kiwi Sizing chart that is only an image. When you replace the image in Shopify, the assistant reads the new one. If the assistant does not find your size chart image, type its metafield in Size guide metafield. Two image metafields with “size” in their names count as no match, so name the right one there too.

Yes. Many stores write one size guide page per product family and link each product to it with a product metafield of the type Page. The assistant reads the table on that page. When the page shows the size chart only as an image, it reads the measurements from the image. It also uses the text on the page, such as “all measurements are in cm”. Your custom app needs the read_online_store_pages scope to read the page. Name the metafield “Størrelsesguide”, “Size guide” or similar, or type it in Size guide metafield.

Can the assistant answer from my Shopify store pages and blog posts?

Section titled “Can the assistant answer from my Shopify store pages and blog posts?”

Yes. With the read_online_store_pages scope on your custom app, KonversAI adds your store pages, such as shipping, returns and about us, and the blog posts of every blog in your store to the knowledge base. KonversAI lists them after a successful Test connection on the Shopify tool, and checks them again every day. Choose the pages and blog posts on Knowledge > Imports: select Open on the Shopify import. See Add your Shopify store pages and blog posts to the knowledge base.

Why does the customer’s contact card show Amount spent and RFM group?

Section titled “Why does the customer’s contact card show Amount spent and RFM group?”

The Shopify tool fills in the contact card in the KonversAI console when the conversation has an email address that matches a Shopify customer. The card shows Amount spent, Orders, Customer since and RFM group, and the customer’s name. See Find a customer contact. These values reach your team in the console only, never the customer. The custom app needs the read_customers scope for this. Add that scope, select Release, install the app again, and select Test connection on the Shopify tool.

How far back can the assistant see orders?

Section titled “How far back can the assistant see orders?”

That depends on one Shopify scope. With read_all_orders on your custom app, the assistant reaches your full order history. Without it, Shopify itself limits the app to the last 60 days, and older orders look as if they do not exist. read_all_orders is a protected scope: request it on the app version in the Shopify Dev Dashboard, select Release, then install the app again and approve the new scopes. The banner on the Shopify tool in the KonversAI console lists Granted scopes, so you can check what your app actually holds. Select Test connection to refresh that list.

Last reviewed . Tell us when a step no longer matches the product.