> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/integrations/e-commerce/magento.md).

# Magento

Set up an AI agent for Magento that looks up orders, payments, tracking and stock live, and answers customers on your storefront, in your helpdesk and in Slack.

eesel's AI agent for Magento is an AI chatbot and assistant for your Magento 2 store. It looks up orders, payments, shipments and stock live, and answers customers in your storefront chat, your helpdesk or Slack.

Your AI teammate is a commerce teammate in Magento. It helps you run your store and answers every customer question. It looks up orders, payments, shipments and tracking numbers, and checks whether an item is in stock. Those lookups happen live, at the moment they are asked.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-a9b96cb016d2b18cf4ade2de75807bcb69e99497%2Fmagento-hero.png?alt=media" alt="A storefront with the eesel chat bubble open, where the agent looks up an order and shows its carrier, tracking number and ship date"><figcaption><p>The agent answering an order question with live Magento data.</p></figcaption></figure>

## Set up eesel in Magento

{% stepper %}
{% step %}

### Ask your agent to connect Magento

Open the chat in your dashboard and ask it to connect Magento. It needs your store base URL and four values from your Magento Admin. It asks for the store URL first. The four values go into a private form, never into the chat.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-31122781738b37ca0d28ddae06485954b23f5945%2Fmagento-connect-chat.png?alt=media" alt="The dashboard chat where the user asks to connect Magento and the agent lists the store URL and the four Magento integration values it needs"><figcaption><p>The agent listing the store URL and the four values it needs.</p></figcaption></figure>
{% endstep %}

{% step %}

### Create the integration in Magento Admin

The four values come from an integration you create once in Magento. In Magento Admin open **System**, then under **Extensions** choose **Integrations**, and click **Add New Integration**. Give it a name, leave both URL fields blank, set the API resource access, then save. Back on the Integrations list, click **Activate**, then **Allow**. Magento shows the four values, masked, on a pop-up you close with **Done**. Copy all four before you close it, and leave the eesel chat open throughout.

A person signs in and does this in Magento Admin. Every screen, and what each resource permission is for, is on [Set up Magento](/integrations/e-commerce/magento/magento-setup.md).
{% endstep %}

{% step %}

### Paste the values into the secure form

Back in the chat, give your agent the store URL. A form opens with one field for each of the four values.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-39481a4ae2fc004dce8c0ee91ded8465d4c53ed5%2Fmagento-secure-form.png?alt=media" alt="A secure form in the dashboard chat with empty fields for Consumer Key, Consumer Secret, Access Token and Access Token Secret, and a Save securely button"><figcaption><p>The secure form, with a field for each of the four Magento values.</p></figcaption></figure>

Paste each value in and click **Save securely**. The values go straight to eesel, never into the chat, and the form expires in 30 minutes.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-4ddcefb70fbba2c6b436639c3fecc388007759df%2Fmagento-secure-form-filled.png?alt=media" alt="The same secure form with all four values filled in and masked, ready to save securely"><figcaption><p>The form filled in, with the values masked.</p></figcaption></figure>
{% endstep %}

{% step %}

### Confirm the connection

Your agent finishes the connection and tells you the store is live. Ask it to read a few of your real orders back. If it cannot read anything, the values or the store URL are wrong, so see Troubleshooting below.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-8fd868ec0eb3b59448e3ca63afbade436f0edb0b%2Fmagento-connected-chat.png?alt=media" alt="The dashboard chat confirming Magento is connected and live, with Magento now listed in the left sidebar"><figcaption><p>The chat confirming the store is connected.</p></figcaption></figure>

**Check it worked.** Magento appears in the left sidebar with your store URL. From a terminal, `eesel status` shows the integration as connected with its source counts.
{% endstep %}

{% step %}

### Check what it can read

Open **Integrations > Magento**. It shows **Connected** with your store URL and buttons to start a chat. Below sit a **Sources** section and an **Actions** section split into **Read** and **Write** groups.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-4313be1c8cc756cb3a5664791195b2044de266f6%2Fmagento-integration-page.png?alt=media" alt="The Magento integration page in the eesel dashboard showing Connected with the store URL, a Magento source row, and the Read and Write action groups"><figcaption><p>The Magento integration page, with the store source row and the two action groups.</p></figcaption></figure>

The **Products** source holds your catalogue. When your Magento integration is allowed to read orders and customers, **Orders** and **Customers** are copied in at connect too. The lookup actions read the store live either way.
{% endstep %}

{% step %}

### Put it to work in Slack

Connecting alone does not start your agent. It needs an automation first.

Ask in the dashboard chat to turn on the [Slack](/integrations/communication/slack.md) mention automation. See [Automations and schedules](/automations-and-schedules/automations-and-schedules.md). A teammate can then ask about any order. Your agent answers in the thread with the customer, items, order status, payment, shipment tracking and current stock.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-0c5110c328be6978484c5dfb523d5d54faf89812%2Fmagento-slack-thread.png?alt=media" alt="A Slack thread where a teammate mentions eesel about an order and your agent answers with the customer, items, status, payment, shipment tracking and current stock for each item"><figcaption><p>An order question answered in a Slack thread.</p></figcaption></figure>
{% endstep %}

{% step %}

### Put it on your storefront

The [chat bubble](/integrations/chat-surfaces/chat-bubble.md) puts the same answers in front of shoppers. A fresh chat opens with your welcome message and a few starter questions.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-ebdbedf8dedf15910a0fe7261e1164939d083222%2Fmagento-bubble-open.png?alt=media" alt="A Magento storefront home page with the eesel chat bubble open on a fresh chat, showing a welcome message and three starter questions"><figcaption><p>The chat bubble on a Magento storefront, open on a new conversation.</p></figcaption></figure>

Ask about stock, and your agent answers with availability and price from the live store.

<figure><img src="https://3732419023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2xXO0947TYoPIhGoBgSE%2Fuploads%2Fgit-blob-95c0d45b2c614fe28ade1c32ac8bcef381a834ea%2Fmagento-bubble-stock-answer.png?alt=media" alt="The eesel chat bubble in full-screen mode on a storefront category page, answering a shopper&#x27;s stock question with availability and price"><figcaption><p>The bubble in full-screen mode, answering a shopper's stock question.</p></figcaption></figure>

Your agent can also show products as cards. On a store with Magento's Luma theme, a shopper can add a product to the cart from its card and see their cart in the chat. A product with options to pick, such as a size, links to its product page instead, and so does every card on other themes.

{% hint style="warning" %}
**Magento needs a different snippet.** Magento loads RequireJS, which sets `define.amd`. While that is set, the plain snippet from the [Chat Bubble](/integrations/chat-surfaces/chat-bubble.md) page never draws the bubble, and no error appears. Use the version below. It clears `define.amd` while the eesel loader runs, then puts it back for Magento's own scripts.
{% endhint %}

In Magento Admin open **Content > Design > Configuration** and click **Edit** on the store view you want the bubble on. Paste the snippet below into the **Footer** section's **Miscellaneous HTML** field. Replace `YOUR_TRIGGER_ID` with the trigger id shown beside the snippet on your eesel Chat Bubble page.

```html
<script>
(function(){
  var TRIGGER = 'YOUR_TRIGGER_ID';
  window.__EESEL_WIDGET_V2_CONFIG__ = { EESEL_TRIGGER_ID: TRIGGER };

  var amd = window.define && window.define.amd;
  if (amd) { window.define.amd = undefined; }
  function restore(){ if (amd && window.define) { window.define.amd = amd; } }

  var script = document.createElement('script');
  script.src = 'https://cdn.eesel.ai/loader.js';
  script.async = true;
  script.onload = function(){
    var t0 = Date.now();
    var poll = setInterval(function(){
      if (window.EeselWidgetWithTrigger || Date.now() - t0 > 10000) {
        clearInterval(poll);
        restore();
      }
    }, 50);
  };
  script.onerror = restore;
  document.head.appendChild(script);
})();
</script>
```

{% endstep %}

{% step %}

### Hand a shopper to your team

When a shopper asks for a person, your agent can take their details and open a ticket in your helpdesk. Tell it how in the dashboard chat, for example: "When a shopper asks to speak to a person, ask for their name and email, create a ticket in our helpdesk with a summary of the chat, and tell them our team will follow up." It writes the rules into its instructions. The ticket then lands in your helpdesk under the shopper's email. See the handover walkthrough on [Chat Bubble](/integrations/chat-surfaces/chat-bubble.md).
{% endstep %}
{% endstepper %}

## Sources, triggers and actions

### Sources

Sources are what your agent can search in your store. eesel copies them when you connect.

| Source        | What your agent reads from it                                             |
| ------------- | ------------------------------------------------------------------------- |
| **Products**  | Your catalogue, with SKUs, pricing, descriptions and variants             |
| **Orders**    | Your orders. Shown only when the integration can read orders              |
| **Customers** | Your customer records. Shown only when the integration can read customers |

A copied order or customer record is a snapshot. Your agent still looks the live record up before it quotes it or acts on it.

Magento does not hand over written content such as a returns policy, a delivery promise or an FAQ. Connect your [website](/integrations/knowledge/website.md) so your agent reads your storefront and policy pages, or upload the documents. See [Integrations](/integrations/overview.md).

### Triggers

Magento has no triggers. Nothing in your store starts an agent run. The trigger comes from a helpdesk like Zendesk, [Gorgias](/integrations/helpdesks/gorgias.md) or Freshdesk, a Slack mention, or the chat bubble. Your agent uses its Magento actions while it handles that conversation. The trigger event is fixed when the automation is created. So a new automation is required for each different trigger event.

### Actions

Actions are what your agent can do in your store:

|           | Action                  | What it does                                                                                                                                                                                                                                                                                                                                                                   |
| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Read**  | Get Order by ID         | Pulls the full details of one order number                                                                                                                                                                                                                                                                                                                                     |
|           | Get Orders by Email     | Finds every order placed under one email address                                                                                                                                                                                                                                                                                                                               |
|           | Get Order Tracking      | Shipment status and tracking numbers for an order, with a link to the carrier's tracking page for UPS, USPS, FedEx and DHL                                                                                                                                                                                                                                                     |
|           | Get Payment Status      | The payment method, whether it cleared, and any balance due                                                                                                                                                                                                                                                                                                                    |
|           | Search Products         | Finds products in your catalogue by name or SKU                                                                                                                                                                                                                                                                                                                                |
|           | Get Product             | Full details of one product from its SKU                                                                                                                                                                                                                                                                                                                                       |
|           | Check Stock Status      | Stock quantity, in-stock flag and backorder policy for one SKU                                                                                                                                                                                                                                                                                                                 |
|           | Get Product Variants    | The sizes and colours a product comes in, each with its own SKU, price and stock                                                                                                                                                                                                                                                                                               |
|           | Get Customer by Email   | Finds a customer by email, with the addresses saved on their account                                                                                                                                                                                                                                                                                                           |
| **Write** | Refund Order            | Refunds a money amount, specific items, or everything still outstanding on the order, recorded as a credit memo. Only an order paid by an offline method (check, bank transfer, cash on delivery) can be refunded here; a card or other online-gateway order is refused, because that refund has to be issued by a person in the Magento admin to reach the customer's account |
|           | Cancel Order            | Cancels an order that has not shipped                                                                                                                                                                                                                                                                                                                                          |
|           | Hold Order              | Pauses fulfilment without cancelling. Useful while someone checks a fraud flag or a bad address                                                                                                                                                                                                                                                                                |
|           | Unhold Order            | Releases a hold so the order carries on                                                                                                                                                                                                                                                                                                                                        |
|           | Send Order Notice       | Sends the customer a notice about an order: an order update, a shipping update, or a payment reminder                                                                                                                                                                                                                                                                          |
|           | Update Customer Address | Corrects one address saved on a customer's account. It does not change an order already placed                                                                                                                                                                                                                                                                                 |
|           | Create Return           | Starts a return for items on an order. Adobe Commerce only. On Magento Open Source, a refund is the way to handle a return                                                                                                                                                                                                                                                     |

You stay in control the whole way. Adjust your AI agent's access to knowledge and its action permissions to your liking. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md).

Two limits:

* **Orders.** An order is found by its exact order number, or by the email address on it. There is no free-text order search, and no lookup by customer name, phone number, date or status. Magento matches an order number letter for letter, so a mistyped number finds nothing.
* **Stock.** A stock check reads one product at a time and needs that product's exact SKU. Your agent takes the SKU off an order, or finds it by searching the catalogue for the product name.

{% hint style="info" %}
**From Claude Code, Cursor or a terminal.** The same setup works as commands: `eesel login`, then `eesel integrations connect magento`, which prints the details that connection method needs. `eesel status` then shows the integration as connected with its source counts, and `eesel automations` lists your automations. Three steps have no command: creating the Magento integration, pasting the four values, and turning an automation on. Use the dashboard chat for those. The Magento Admin part is a human step. Wait for a person to create the integration and paste the four values. Wait for the connection status to change, and do not retry. Full command reference: [The eesel CLI](/apis-and-developer-resources/cli.md). Step-by-step: [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md).
{% endhint %}

## Limitations

* **No Magento triggers.** Nothing in your store starts your agent. A helpdesk ticket, a Slack mention or the chat bubble does.
* **Orders are found by exact order number or email.** There is no free-text order search, and no lookup by name, phone number, date or status.
* **Stock is checked one SKU at a time.**
* **Returns need Adobe Commerce.** Magento Open Source has no returns, so Create Return is unavailable there.
* **Refunds only on offline payments.** Your agent refunds orders paid by check, bank transfer or cash on delivery. A card or other online-gateway refund has to be issued by a person in the Magento admin.
* **No written content from Magento.** Returns policies, delivery promises and FAQs come from your [website](/integrations/knowledge/website.md) or uploaded documents.
* **The chat bubble needs the wrapped snippet** shown above, because Magento's RequireJS stops the plain one from appearing.
* **Magento sets the ceiling.** The API resource access you grant the Magento integration is the most your agent can reach. Grant read-only access and it can look things up but never change an order. [Set up Magento](/integrations/e-commerce/magento/magento-setup.md) lists what each resource is for.
* **Magento 2 only.** The setup screens and the four-value connection are Magento 2's.

## Troubleshooting

<details>

<summary>The connection keeps failing, or reads "needs reconnect"?</summary>

Check the store URL is exact, including `https://`, with no trailing path. Make sure the integration is **Activated** in Magento, not only saved. Then confirm you pasted all four values, and that every one came from the **same** integration.

</details>

<details>

<summary>It worked, then every Magento read started failing?</summary>

Re-activating the integration in Magento Admin issues a new set of four values. The old ones stop working at that moment. Ask your agent to reconnect Magento, and paste the new four values into the secure form it opens.

</details>

<details>

<summary>Your agent cannot find an order, or a lookup comes back empty?</summary>

The integration needs read access to the matching resource: **Sales / Orders** for order lookups, **Sales / Shipments** for tracking, **Catalog / Products** and **Catalog / Inventory** for stock. Then check the identifier, because Magento matches it literally. Look the customer's orders up by their email address and compare the number against that list.

</details>

<details>

<summary>A refund, cancel, hold or unhold fails?</summary>

A refund needs the **Sales / Invoices** read resource and both credit memo resources: the Orders action **Sales > Operations > Orders > Actions > Credit Memos** to issue the refund, and the top-level **Sales > Operations > Credit Memos** to read it back and confirm the money moved. Grant only one and the agent can move the money but reports the refund as failed. It also needs an invoice on the order to refund against, and the agent only refunds orders paid by an offline method (check, bank transfer, cash on delivery); a card or other online-gateway order is refused, because that refund has to be issued in the Magento admin to reach the customer's account. Cancel, hold, unhold and order notices need write access on **Sales / Orders**. The order also has to be in a state that allows it. You cannot cancel an order that already shipped, or release a hold on an order that is not on hold.

</details>

<details>

<summary>A write action did not happen?</summary>

Open the run on your **Activity** page. If the action is waiting on a person, approve it and it runs.

</details>

<details>

<summary>The chat bubble never appears on your storefront?</summary>

Magento's RequireJS loader stops the plain snippet from drawing the bubble, and nothing reports an error. Use the wrapped snippet in the storefront step above. For a strict Content Security Policy, allow `https://cdn.eesel.ai` for scripts and connections.

</details>

## FAQ

<details>

<summary>How do I add an AI agent to Magento?</summary>

Create an integration in Magento Admin, then ask your agent in the eesel dashboard chat to connect Magento and paste the four values into the secure form it opens. Then ask it to turn on an automation, such as the chat bubble or the Slack mention automation. The steps are in [Set up eesel in Magento](#set-up-eesel-in-magento).

</details>

<details>

<summary>Can the Magento AI agent answer order status questions?</summary>

Yes. Your agent looks the order up live by its order number or the customer's email address, and reads its status, payment, shipments and tracking numbers. A mistyped order number finds nothing, because Magento matches it letter for letter.

</details>

<details>

<summary>Can the Magento AI agent process refunds?</summary>

Yes, for orders paid by an offline method such as check, bank transfer or cash on delivery. It refunds an amount, specific items, or everything outstanding, as a credit memo. Card and other online-gateway orders are refused, because that refund has to be issued in the Magento admin to reach the customer.

</details>

<details>

<summary>Can I connect Magento to ChatGPT or Claude?</summary>

Yes, through eesel. Once Magento is connected, you can talk to your eesel agent from ChatGPT, Claude or Cursor, and it works with your Magento data. See [Use eesel from ChatGPT](/apis-and-developer-resources/use-eesel-from-chatgpt.md), [Use eesel from Claude and other assistants](/apis-and-developer-resources/use-eesel-from-claude-and-other-assistants.md) and [Claude Code and MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md).

</details>

<details>

<summary>Does connecting Magento let my AI agent change orders on its own?</summary>

No. Connecting only gives your agent access to your store. It does not act until you create an automation and turn actions on.

</details>

<details>

<summary>Is my Magento data live or copied on a schedule?</summary>

Both. Order, payment, shipment and stock lookups read Magento live, at the moment they are asked. Your product catalogue is copied in when you connect, so your agent can search it. So are your orders and customer records, when the integration can read them.

</details>

<details>

<summary>Can my AI agent learn my product and policy content from Magento?</summary>

Products yes, policies no. Your catalogue is copied in when you connect. Magento holds no written content such as a returns policy or an FAQ, so connect your [website](/integrations/knowledge/website.md) or upload the documents.

</details>

<details>

<summary>How do I disconnect Magento from eesel?</summary>

Open Magento under Integrations in the left sidebar and remove the connection. To revoke access on Magento's side as well, delete or deactivate the integration you created in your Magento Admin.

</details>

## Related pages

* [E-commerce Sales Rep](/use-cases/e-commerce-sales-rep.md) for the job your agent does on a store
* [Set up Magento](/integrations/e-commerce/magento/magento-setup.md) for the full Magento Admin walkthrough
* [Chat Bubble](/integrations/chat-surfaces/chat-bubble.md) for putting your agent on the storefront
* [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md) for choosing what your agent may do
* [Integrations overview](/integrations/overview.md) for how sources, triggers and actions fit together
* [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eesel.ai/integrations/e-commerce/magento.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.