Shopify tool

The Shopify tool lets an agent manage a Shopify store: products and variants, inventory, collections, tags and metafields, orders, fulfillment with tracking, refunds, draft orders, customers and discount codes. It works through Shopify's GraphQL Admin API. The agent picks one of 47 actions each time: built-in actions for everyday store work, and three general actions for anything else in the Admin API. One configuration is one store. Connect your store, then add the tool to an agent.

Two ways to connect

There are two ways to connect a store. Both give you the same kind of configuration, and the agent, the blueprint and the connection test work the same either way.

• Connect with Shopify - you approve Hania's own Shopify app on Shopify's page. There are no keys to copy, and Hania keeps the connection fresh for you. This is waiting for Shopify's approval, so it doesn't work on your store yet.
• Connect manually - you create your own app in the Shopify Dev Dashboard and enter its Client ID and Client Secret with your store address. This works on any store today.

What it can do

The agent picks one action each time. The 47 actions, by area:

• Store - get_shop, list_locations.
• Products - list_products, get_product, create_product, update_product, delete_product, create_variants, update_variant, set_products_status.
• Inventory - get_inventory_levels (stock per location: available, on hand, committed, incoming and reserved), set_inventory (set an exact amount) and adjust_inventory (add or remove), per location.
• Collections - list_collections, get_collection, create_collection, update_collection, delete_collection, add_to_collection, remove_from_collection.
• Tags & metafields - add_tags, remove_tags (product, order or customer), set_metafield.
• Orders - list_orders, get_order, update_order, mark_order_paid, close_order, open_order, cancel_order.
• Fulfillment & refunds - create_fulfillment, update_tracking, create_refund.
• Draft orders - list_draft_orders, create_draft_order, complete_draft_order, delete_draft_order.
• Customers - list_customers, get_customer, create_customer, update_customer, delete_customer.
• Discounts - create_discount, delete_discount.
• Anything else in the Admin API - graphql_schema, graphql_query, graphql_mutation. See the general GraphQL actions.

What's new. A product can now be created with options (for example Size), several variants and images in one step, and variants can be added to an existing product later. Up to 50 products can be set to active, draft, archived or unlisted at once. A collection can be hand-picked, rule-based (by tag, title, product type or vendor, matching all of the rules or any of them), or both, with a sort order. A discount can be a fixed amount as well as a percentage. It can be limited to certain products or collections, a minimum spend or quantity, a number of uses, once per customer, or certain customers or customer segments. And long lists can be read page by page.

Anything else: the general GraphQL actions

For anything the built-in actions don't cover, the agent can use Shopify's GraphQL Admin API directly. It works the same way as Shopify's own MCP server. The agent first looks up the part of the Admin API it needs with graphql_schema. Then it runs a read with graphql_query or a change with graphql_mutation.

• The lookup stays inside Hania - graphql_schema answers from a copy of Shopify's Admin API description (version 2026-10) that Hania keeps. It doesn't contact your store.
• Every request is checked first - before a request reaches your store, Hania checks it against that description. A field that doesn't exist, or a value of the wrong type, is caught there and the agent corrects it.
• One request per call - graphql_query only reads, and graphql_mutation only changes.
• It can only do what the app is allowed to - the general actions are limited by the store's app permissions. Connect with Shopify asks for the eight listed in What Hania asks for. If a request needs a permission the connection doesn't have, the error names it, for example "needs write_files".

Some changes are blocked in the general action. If the agent tries one, Hania refuses it:

• refunds (use create_refund instead)
• deleting orders
• capturing, charging or voiding payments
• changing gift cards
• changing staff
• deleting or publishing themes, and changing theme files

The safety settings apply too. graphql_query counts as a read and graphql_mutation counts as a change. With the default settings, that means graphql_mutation is blocked in scheduled or triggered runs unless the agent has "Allow destructive actions in autonomous runs" turned on. In chat, it follows the agent's approval rules like any other change.

Ready-made Shopify agents

The quickest way to a working agent is a blueprint. There are three for Shopify, all in the e-commerce category of the blueprint gallery, and they're for different people.

• Shopify Store Manager - your own assistant for running the store. It has full store access and is for you and your staff, not for shoppers. All you add is the Shopify connection from this guide, and the rest of the agent is set up for you.
• Shopify Sales & Support - talks to your shoppers and customers, for example in a chat on your website. It's described below.
• Shopify Sales Chat - the same kind of help for shoppers who message you on WhatsApp, Messenger or Instagram. See Ready-made messaging agents.

What Shopify Sales & Support does

• Products and stock - it answers questions about your products, prices and what's available. It only shows products that are active in your store, and it goes by Shopify's own "available for sale" flag.
• Help choosing - it helps people choose and can suggest a fitting extra item. You decide how actively it does that when you set it up: gently, balanced or actively.
• Orders - it gives the order status, items and tracking, but only when the order number and the email on the order match what the shopper gives. A shopper without an order number can confirm their email with a 6-digit code instead. It never shares a delivery address, phone number or payment details.
• Buying - it sends the product's page link, or a checkout link for several items. The shopper pays on your own Shopify checkout. The agent never takes or records a payment.
• It says it's an AI - in its first reply.
• It never changes your store - and it never makes or promises discounts, prices, delivery dates or refunds.
• Your team handles the rest - refunds, returns, exchanges, cancellations, order changes and complaints go to the support contact you give it. If you connect an email account (optional), it also emails your team a short summary.
• Store policies come from you - it answers questions about shipping, returns or sizing from what you add to the agent's knowledge, during setup or later. It can't read your policy pages from Shopify. If you haven't added a policy, it says it doesn't have that information and gives your support contact.

The connection we recommend for it

Give this agent its own store app with only five permissions. Follow the manual steps, and in step 3 add exactly these: read_products, read_orders, read_customers, read_merchant_managed_fulfillment_orders and write_draft_orders. Then declare protected customer data (step 4) as usual.

Those five let it read products and orders and make checkout links, and nothing more. So Shopify itself refuses any other change to your store, whatever a shopper writes in the chat. A connection with more permissions also works, but this is the safer choice for an agent that talks to the public.

Adding it to your website

The chat goes on your store with one snippet. Get your chat widget's embed snippet, then in your Shopify admin go to Online Store → Themes → Edit code, open Layout → theme.liquid, paste the snippet on a new line just above </body>, and save. Shopify notes that a theme update can remove code changes like this one. If the chat disappears after an update, paste the snippet again.

After the website, you can connect the same agent to WhatsApp, Messenger, Instagram or Telegram too, from Channels in Hania. See Messaging channels.

Good to know

• The verification email - the 6-digit code a shopper gets comes from Hania, with the subject "Your verification code", and it doesn't name your store. You may want to tell your customers to expect it.
• Orders from the last 60 days - older orders aren't visible. That's Shopify's default for apps. For an older order, the agent gives your support contact instead.
• Page links need the online store - a product has a page link only when it's published to your online store. Otherwise the agent offers a checkout link.
• Each checkout link is a draft order - you'll see it under draft orders in your Shopify admin. Unpaid ones stay open there, and you can delete them.
• Policies must be added - add them to the agent's knowledge, as text or page addresses.

Connect with Shopify

Once it's approved, this is the short way. You approve Hania on Shopify and come back connected, with nothing to copy.

1. Go to Tools, choose Add tool, then Shopify. If an agent asks for Shopify in a chat, the same form is in the chat card.
2. Enter your store's address, for example my-store.myshopify.com. Just the store name, my-store, also works.
3. Choose Connect with Shopify. Shopify opens in a new tab and asks you to approve Hania for that store.
4. Approve it. The new tab comes back to Hania and confirms the connection. The form you started from updates by itself, so you can close the new tab. If you started from a chat, the agent carries on by itself.

If your browser blocks the new tab, use the Open the approval page link in the form. If you're signed out when Shopify sends you back, sign in as normal and the connection finishes. The approval link lasts 10 minutes and works once.

After you connect

• Its name - the connection is saved as Shopify (my-store.myshopify.com). When you open it, it shows Connected and your store address instead of the credential fields.
• It renews by itself - Hania renews the connection's access automatically, so there's nothing to rotate.
• Needs reconnecting - if Shopify stops accepting the connection, for example because Hania was uninstalled from the store, its card on the Tools page shows Needs reconnecting with the reason. Open it and choose Reconnect. That runs the same approval again and keeps the configuration's safety settings as they are.

One workspace per store

A store connected with Connect with Shopify belongs to one Hania workspace. That's because of a Shopify rule: a new approval cancels the one before it. If the store is already connected this way in another workspace, Hania refuses with: "This store is already connected with Connect with Shopify in another workspace. Disconnect it there first, or connect it here with your own app's credentials."

The same rule applies inside one workspace. If you connect the same store a second time, the newer connection takes over, and the older one shows "This store was connected again, which ended this connection." Choose Reconnect on the one you want to keep, or delete the one you don't need.

What Hania asks for

On Shopify's approval page, Hania asks for access to products, inventory, locations (read only), orders, draft orders, customers, discounts, and merchant-managed fulfillment orders. In Shopify's own terms: write_products, write_inventory, read_locations, write_orders, write_draft_orders, write_customers, write_discounts and write_merchant_managed_fulfillment_orders.

Coming soon: install from the Shopify App Store

After Shopify approves the app, you'll also be able to install Hania from the Shopify App Store. When you open Hania inside your Shopify admin, it shows Link to your Hania workspace. That opens Hania, you sign in, and the store connects to your workspace. The link lasts 10 minutes. If it runs out, open Hania in your Shopify admin again to get a new one.

At that point, Connect with Shopify in Hania will stop asking for your store address and will take you to Hania's page on the Shopify App Store instead. Until then, the address field stays.

Connect manually (your own app)

This works on any store today. In the Shopify form, choose Enter the details manually instead.

Before you start

You need:

• A Shopify store. Its address ends in .myshopify.com.
• Access to the Shopify Dev Dashboard at dev.shopify.com, in the same organization as your store. An app's Client ID and Secret only work for stores in that app's own organization.

Shopify no longer lets you create new custom apps inside the Shopify admin. The Dev Dashboard is the only place to make one. From your store admin you can get there through Settings → Apps → Develop apps → Build apps in Dev Dashboard.

Steps

1. Create an app. In the Shopify Dev Dashboard, choose Create app and give it any name, for example "Hania Integration".
2. Add an app URL. Shopify asks for one when you create the app. Hania doesn't use it, so any address you control, such as your own website, is fine.
3. Give it permissions. In the app version's Access section, add the permissions your agents need. The same list Connect with Shopify uses covers everything the tool does: write_products, write_inventory, read_locations, write_orders, write_draft_orders, write_customers, write_discounts and write_merchant_managed_fulfillment_orders. Fewer is fine. An action the app isn't allowed to do fails with a clear permissions error, and the agent tells you.
4. Declare protected customer data. In the app's settings, find Protected customer data access and declare customer data, with the name, email, phone and address fields. For an app on your own store this takes effect straight away, with no review. See the note below. This is the step people miss.
5. Install the app on your store. In the Dev Dashboard, open the app, go to Installs, choose Install app, pick the store and choose Install.
6. Copy the credentials. Open the app's Settings page and copy the Client ID and Client secret. Enter them in Hania with your store's myshopify.com address, and save.

Shopify no longer gives new apps a fixed access token, which is why you enter a Client ID and Secret instead. Hania swaps them for short-lived access tokens behind the scenes, so you never see or manage a token.

Older apps with a fixed token

If you already have an older custom app that was created inside the Shopify admin, its fixed Admin API access token (it starts with shpat_) still works. Enter it in the Admin API Access Token field with your store address, and leave the Client ID and Secret blank. These tokens can't be rotated. The only way to get a new one is to uninstall and reinstall the app. For a new app, use the Client ID and Secret steps above.

Field reference

These are the fields on a manual configuration. Only the store address is required, plus either a Client ID and Client Secret or an Admin API Access Token. A configuration made with Connect with Shopify hides all of them, because Hania manages its credentials.

• Store Domain (required) - your store's myshopify.com address, for example my-store.myshopify.com. Just the store name also works. A custom domain won't: it has to be the myshopify.com address.
• Client ID - from your app's Settings page in the Shopify Dev Dashboard. Used together with the Client Secret.
• Client Secret (secret) - from the same Settings page. Hania swaps it for short-lived access tokens automatically. It's stored encrypted and never shown again after you save.
• Admin API Access Token (secret, older apps only) - only for an older custom app created in the Shopify admin with a fixed shpat_ token. Leave it blank when you use a Client ID and Secret.
• API Version (optional, default 2026-10) - the Shopify Admin API version. Leave the default unless you know you need another one.
• Refresh Token - filled in by Connect with Shopify only. Leave it blank.

Good to know

Beyond the actions above:

• Search and limits - list actions accept Shopify's search syntax in query (tag:vip, status:draft, email:[email protected]) and return up to 50 results at a time. When there are more, the agent can ask for the next page. Shopify's search takes a few seconds to catch up after a change, so the agent reads a record again by its id after changing it.
• Inventory is per location - with one location it just works. With several, the agent lists them and picks one, or asks you which.
• Cancelling takes a moment - cancelling an order finishes a moment later on Shopify's side. Collection changes take effect straight away.
• Prices are in the store's currency, written as decimals (for example 19.99). A discount is either a percentage off (1 to 100) or a fixed amount off (for example 10.00).
• Images are added from a public https link. Shopify takes a moment to process them after the product is saved.
• Removing a product from a hand-picked collection - if it was the only hand-picked product, Shopify needs that part of the collection removed, and Hania does that for you. Any rule-based part of the collection stays as it is.
• Shopify won't delete a customer who has orders - the agent reports that clearly.

Hania enforces a few limits itself, so you can rely on them. The agent never takes payment: completing a draft order always leaves it waiting for payment, and marking an order paid is its own separate action. It never permanently deletes orders: there's no action for that. And it never emails customers unless you tell it to: fulfillment and cancellation emails are off by default. The general GraphQL actions follow the same limits: deleting orders and capturing or voiding payments are blocked there too.

Troubleshooting

• "access-token exchange failed" - the store address, Client ID or Client Secret is wrong, or the app isn't installed on that store. The app also has to be in the store's own organization. Check steps 5 and 6 of Connect manually.
• ACCESS_DENIED on customers or draft orders - protected customer data wasn't declared (step 4). Declare it and try again.
• ACCESS_DENIED on anything else - the app doesn't have that permission (step 3). Add it in the app's Access section.
• Store address rejected - it has to be the myshopify.com address, not a custom domain.
• THROTTLED (429) - Shopify slowed the requests down. Hania waits as long as Shopify asks and sends the request once more by itself. If Shopify asks for a longer wait, the agent is told and can try again later.
• "blocked" from graphql_mutation - that change is one Hania refuses in the general action (see the general GraphQL actions). Use the built-in action if there is one, for example create_refund, or make the change in your Shopify admin.
• A GraphQL validation message, for example "Cannot query field … on type …" - Hania caught a request that doesn't match Shopify's API before it reached your store. The agent usually corrects it and tries again.
• SHOP_INACTIVE (403) - the store is paused or closed on Shopify's side.
• "shopify rejected the request: field.path: message" - Shopify didn't accept a value. The agent usually corrects it and tries again, so you may see this in a run before the action works. The text comes straight from Shopify.

With Connect with Shopify, you may see one of these in the tab that comes back to Hania. To try again, close that tab and choose Connect with Shopify again in the form you started from.

• "That approval link expired or was already used" - more than 10 minutes passed before you approved, or the same approval was used twice.
• "The approval came from a different site or store than the one you started with, or couldn't be verified" - what came back from Shopify didn't match the store you started with.
• "Couldn't finish the connection" - something else went wrong, for example access was taken away on Shopify while you were approving. Check the app is still installed on the store.
• Nothing happens and you stay on Shopify - Hania's app isn't approved for your store yet. See the note at the top of Connect with Shopify and connect manually instead.
• "This store is already connected with Connect with Shopify in another workspace" - see One workspace per store. Disconnect it in the other workspace first, or connect it here manually.

Safety in autonomous runs

Like every tool, the Shopify tool has safety settings (read-only, destructive, sends data externally). They decide what an agent may do in a scheduled or triggered run, when nobody is watching. This tool can delete products, collections and customers and cancel orders, so a new configuration starts with Read-only off, Destructive on and Sends data externally on. That means destructive actions are blocked in those runs unless you turn on the agent's "Allow destructive actions in autonomous runs". This applies to both ways of connecting, and reconnecting never resets settings you've changed.

The tighter control is the app's permissions. Give it only what the agent needs, and Shopify itself enforces the limit. Interactive chat isn't affected by these settings.

Security

The Client Secret and any fixed access token are stored encrypted and are never sent back by the API. The console only shows whether each one is set. The short-lived tokens Hania gets with the Client Secret aren't shown either. If you edit a configuration and leave a secret blank, the stored one is kept. To replace it, type the new one.

A connection made with Connect with Shopify works the same way. Its credentials are stored encrypted, never shown to you, and renew by themselves. Saving the configuration can't wipe them, so you can rename it or change its safety settings at any time. To take access away, uninstall the Hania app from the store in your Shopify admin, or delete the configuration in Hania.