# Maplith for e-commerce

How the AI agent a web shop already uses handles the everyday exceptions with Maplith — sold out while the ads run, a late parcel, returns climbing on one product, a support case that needs the policy — each as a before and after, with the pieces the agent uses.

A web shop’s expensive mistakes happen between its systems: the shop knows the stock, the ad platform knows the spend, the helpdesk knows who is waiting, and the procedure sits in a document nobody opens. Your AI agent can handle each of these — if it knows where to look, what matters today, how your business handles it and whether it may act. Maplith gives it exactly that. Your agent drives; Maplith is its map and its alarm clock. Your systems stay the source of truth, the agent acts in them with your credentials, and Maplith holds the logic.

The worked example on this page is Acme Commerce, a fictional web shop built for this demo: the company, its people, its customers, the device brands, the suppliers and the competing chains are all invented, and nothing in the data comes from any customer.

## Workflows

Four workflows every web shop runs. Each shows what an agent has to do without Maplith, and the Maplith pieces it uses instead. Figures come from the worked example’s exported data, twelve months whose last day is 2026-08-31. Where a step needs live rules, it says so: live rules are in early access and being built now; everything else on this page ships today.

### Sold out, and the ads keep running

Stock reaches zero in the shop; the ad platform keeps paying for clicks on it.

**Without Maplith.** Stock sits in the shop and the reporting database, spend sits in the ad platform, and nobody owns the space between. In the worked example a leather case was out of stock from 2026-07-14 to 2026-07-29, and one campaign spent DKK 5,630 on it across those sixteen days — 1,599 clicks, not one conversion — while the shop’s own marketing rules say to pause ads the day stock reaches zero. An agent without a map has to find both exports, guess how the ad platform’s rows join the stock (the catalogue spells seven re-listed products differently), read a year of daily rows to notice, and start over tomorrow.

**With Maplith:**

1. **Your rules** — An admin writes the rule once, from the map’s own names: **stock on hand is zero and ad spend over the last day is above zero — per product.** A product is reached only through joins Maplith tested against the rows. The rule is judged when a scan finishes and, for a connected system, daily or weekly between scans; its first judging is its baseline, so a product already sold out then raises nothing, and a product fires when it starts matching.
2. **Signals** — `list_signals` returns a `rule_fired` signal for that product, with the figure behind each condition.
3. **Task context** — `get_task_context` returns the product, the verified route from ad spend to stock, the marketing rules if the shop keeps them as a playbook, what was done the last time, and the operation the rule suggests — pause the ad set — with the key’s policy for it.
4. **The action gate** — `request_action` to pause that ad set: allowed, pending a person, or denied. An allowed answer can carry a grant good once for that ad set; the agent pauses it in the ad platform with the shop’s own credentials.
5. **Record and value** — `record_action` records what was done — with the spend the ad platform says it stopped, when the agent has that figure — so the next judging does not raise it as though nobody had looked, and **What you got** counts it.
6. **Live rules (early access)** — Instead of waiting for the next judging, the shop’s own automation — the kind a shop platform already runs when stock changes — reports only the observation that a product reached zero, and Maplith turns it into the same signal and task context within minutes.

### A parcel is late: tell the customer before they ask

An order misses its delivery promise; the customer has not written yet.

**Without Maplith.** The helpdesk hears about a late parcel when the customer writes. In the worked example, where-is-my-order is the most frequent tag in the helpdesk export — on 859 conversations over the year. Each answer means finding the order in the shop, the delivery in the carrier’s data, the customer in the helpdesk and the tone the shop uses, by hand, after the customer is already worried.

**With Maplith:**

1. **Live rules (early access)** — Maplith compiles from the map what counts as late for this shop; the shop’s own shipping automation checks it and reports back the order that crossed the line — an observation, not a copy of the order.
2. **Signals** — With live rules, Maplith turns the observation into a signal for that order.
3. **Route** — `route` from the order to the helpdesk conversation tells the agent which system holds each, by which key, and the rate Maplith measured for each hop. The agent reads the order and the customer in those systems, with its own credentials.
4. **Playbooks** — The playbook for delayed parcels — the shop’s own words on what to say and what to offer — arrives inside `get_task_context`.
5. **The action gate** — `request_action` to reply to the case: the shop decides per key whether a person approves every message, or only those whose offer is above a limit.
6. **Record and value** — `record_action` writes what was sent; the action log shows the request, the decision and the outcome.

### Returns that do not fit

Refunds on a few products lean to “does not fit”, and the reason sits in another system.

**Without Maplith.** Refunds sit in the shop with a reason, fit questions sit in the helpdesk, and which device a product fits sits in the catalogue. In the worked example three active catalogue products have an empty compatibility field; forty-four helpdesk conversations tagged does-it-fit name one of them, and their refunds lean heavily to “does not fit” where the shop’s refunds are otherwise spread evenly across reasons. No single system shows that, and an agent reading them one by one has to guess how they join.

**With Maplith:**

1. **Your rules** — A rule the shop writes: **refunds over the last seven days above a number it chooses — per product.**
2. **Signals** — When a product crosses it, a `rule_fired` signal names the product and the count.
3. **Ask** — `ask`: “why could returns be rising on this product, and what does the map know about it?” The answer cites the objects and joins it rests on with their measured rates, any open finding on the product, and what the map could not establish.
4. **The map** — The map shows where the product’s compatibility lives and how the catalogue joins the shop — and where two systems spell the same product differently, the join says how many rows do not match rather than guessing.
5. **The action gate** — `request_action` for an operation the shop declared — for example, opening a task for the catalogue owner — decided by the key’s policy.
6. **Record and value** — `record_action` writes what was done, so the next firing’s context shows it.

### A support agent asks the map how to handle a case

A customer wants to return an item after the window has closed.

**Without Maplith.** A customer asks to return an item 50 days after delivery. The policy says 30 days, with an exception only when the customer service lead tags the conversation and writes the reason. In the worked example six refunds were requested 44 to 62 days after delivery and paid anyway, with no exception recorded; nine other late requests were refused, as the policy says. Without a map, a support agent — a person or an AI — has to know the policy exists, find it, find the order and its delivery date, and decide alone.

**With Maplith:**

1. **Playbooks** — The returns playbook — drafted by Maplith from the shop’s own returns policy and put in use by an admin — reaches the helpdesk’s AI as an MCP prompt or resource, or as a skill file.
2. **Ask** — `ask`: “where do I find the delivery date for an order, and what do I check before a late return?” — answered from the part of the map the key may see, never from rows.
3. **Route** — `route` from the conversation to the order says where the delivery date lives and by which key; the agent reads it in the shop.
4. **The action gate** — A refund outside the window is an exception. The shop sets issuing a refund to need a person’s approval — always, or above an amount — so the request waits as pending until a workspace admin decides, and the agent learns the decision by asking again. Maplith never issues the refund: the agent does, when the answer is yes — and where Maplith signs grants, with a grant bound to that order and amount.
5. **Record and value** — `record_action` writes what was done; the action log shows who approved it.

## The pieces

| Piece | Tool | What it gives the agent | Status |
|---|---|---|---|
| The map | `get_object` | Where each thing lives and how the systems join, with the rate Maplith measured for every join it could test. | live |
| Your rules | — | Conditions the business writes from the map’s own names, judged for each product, order or other group it chooses. | live |
| Signals | `list_signals` | What needs doing, as typed events to poll instead of re-reading the map. | live |
| Task context | `get_task_context` | A single call with everything a signal needs, including the playbooks and what the key may do. | live |
| Ask | `ask` | One question in plain language, answered from the map with citations — never from rows. | live |
| Route | `route` | The shortest verified join path from a start object to a target: which system, which key, how much to trust each hop. | live |
| Playbooks | — | How the business handles it, in its own words — as MCP resources, prompts and a skill file. | live |
| The action gate | `request_action` | Allowed, pending a person, or denied — before the agent acts, with a grant good once. | live |
| Record and value | `record_action` | What was done, so the next judging does not raise it as though nobody had looked — and counted in “What you got”. | live |
| Live rules | — | Maplith compiles what to check live; the business’s own automation reports only what it observed; Maplith turns it into a signal within minutes. | early access |

## What stays with you

Maplith builds the map from your export files and deletes them after the build; what it keeps is the map, which may quote example values and evidence. During a build, samples of the files, and in the findings step whole files, go to the model provider — [Security](/security) says where and for how long. Maplith tries to mask email local parts, Danish CPR numbers, IBANs, card numbers, the names of people in your export's own name columns and the terms you add yourself: a best-effort safeguard, not a guarantee. You decide what your export contains.

Your agent acts in your systems with your credentials. Maplith never performs an action and never holds those credentials: it decides whether an action may go ahead, and keeps the log.

## Try it

The web shop map has its own public read-only key. It serves Acme Commerce, the fictional web shop on this page, on the same production MCP endpoint a real workspace uses:

```
claude mcp add maplith --transport http https://app.maplith.com/api/mcp \
  --header "Authorization: Bearer mlk_demo_acme-ltyWYChCrYzO8KOec-8BX-yO"
```

Then ask: "call get_map_overview" · "list_findings" · "list_signals". The key is read-only and rate-limited.

The fastest way to see these workflows on your own shop is to build your own map from your exports — the first one is free.

The Acme Commerce map, built on 2026-11-01, holds 19 objects, 53 relations, 4 processes, 68 metrics and 18 findings: read from the demo workspace with the key above less than an hour ago, so `get_map_overview` gives you the same numbers unless the map has been rebuilt since.

## The worked example: a web shop, mapped

Every figure above comes from Acme Commerce, a fictional web shop. Here it is end to end: the company, the systems it exports from, and the situations only a cross-system map can see.

### The company

Acme Commerce sells phone and tablet accessories — cases, screen protectors, chargers, cables — from its own web shop. Fifteen people in Aarhus, 10,550 orders and DKK 3.3 million of revenue excluding VAT over the twelve months the data covers, **2025-09-01 to 2026-08-31**. The last day in the data, 2026-08-31, is "today" in the demo's story.

Six of the fifteen pack parcels. Of the rest, one person owns the ads, the pricing and the competitor watch, one owns the reorders and the suppliers, one owns the returns, one owns the margin report, one owns the catalogue. Nobody owns the space between them, which is where this map earns its keep.

The exports come from a generator written for the demo. It is deterministic: the same data comes back every time, so every number on this page can be re-derived from the files rather than remembered.

### The systems

Eight systems, exporting in the formats their own export buttons produce — no integration project, no IT ticket.

| System | What its export holds |
|---|---|
| Web shop | Products, orders, order lines, refunds |
| Reporting database (built in-house, dumped nightly) | Units, revenue, purchase price, margin and stock per product per day |
| Product information management | Device compatibility, EAN, product status |
| Ad platform | Spend, clicks and conversions per campaign and product per day |
| Purchasing | Suppliers with their lead times, purchase orders with inbound freight, order lines |
| Helpdesk | Customer conversations, tagged (where-is-my-order, return, does-it-fit, new-device…) |
| Competitor price feed | A daily price per device model and category at three competing chains |
| Written procedures | The returns policy, the reorder rules, the marketing rules, how margin is measured, the device launch calendar |

The procedures matter as much as the tables. A refund 50 days after delivery is only a problem because the policy says 30 days; ad spend on an empty shelf is only a problem because the marketing rules say to pause the day stock reaches zero. Maplith reads both: to a scan, the procedures are files like any other.

The demo data holds no real personal data.

### The signals

Every figure below comes from the twelve months of exported data whose last day is 2026-08-31 — the day the demo's story is set on. Six situations are planted in those exports on purpose, and each one is a disagreement between two systems that neither system can see on its own.

- **Ads kept paying for a sold-out product.** The Kestrel S4 leather case was out of stock from 2026-07-14 to 2026-07-29 — the purchase order that would have refilled it was due on 07-10 and arrived on 07-30. Workflow: [Sold out, and the ads keep running](/industries/e-commerce#sold-out-while-ads-run).
- **Spend against stock that does not move.** A tablet folio sells about one a week, and 224 units were still in the warehouse on the last day of the data, after a 240-unit delivery landed at the start of May. From June its campaign spent DKK 16,160 against DKK 5,187 of revenue.
- **Products nobody can tell the fit of.** Workflow: [Returns that do not fit](/industries/e-commerce#returns-climb).
- **Refunds outside the return window.** Workflow: [A support agent asks the map how to handle a case](/industries/e-commerce#support-case).
- **The margin everyone steers by leaves out freight.** The reporting database defines margin as revenue minus purchase price. Finance's own procedure says the margin in the weekly report is after inbound freight — which sits on the purchase orders — and the carrier's shipping cost, which sits on the orders. Over the year those come to DKK 526,459 — about a fifth of the margin the report shows, and enough that the reported figure is about a quarter higher than finance's own definition produces. Every decision taken on that number is taken on a margin that does not exist.
- **The same product under two codes.** Seven products were re-listed in the web shop in March 2026 under new codes and the catalogue kept the old ones. The reporting database and the ad platform use the web shop's codes, so a join from sales to compatibility or EAN misses those seven — and a rule written over that join would act on the wrong product.

Those six are in the data, and there is a script in the repo that checks each of them against the exports themselves, with no model involved — that is how we know the exports contain them rather than taking the answer key's word for it. Whether a scan of the exports **finds** them is a separate question, and a separate measurement — an eval scores the map's findings against the answer key. **This page publishes no discovery score and no count from the demo workspace**, because a number on a marketing page that nobody can re-derive is worth less than the sentence it sits in.

Four further situations are in the data and deliberately out of that score: a sales spike that needs a reorder now, a device announcement that should stop the reordering of the old model's accessories, a competitor's two-week price campaign, and a product that is out of stock on the last day of the data with its ads still running. None of them is a one-scan discovery.

## For AI agents

If you are an AI agent working for a web shop, Maplith is the part of each task you would otherwise rebuild from zero: where the data lives, how the systems join, what needs doing, how the shop handles it, and whether you may act. Connect to `https://app.maplith.com/api/mcp` with the agent key your human gives you (or over OAuth), then:

1. `list_signals` with `unacted: true` — what needs doing, instead of scanning exports.
2. `get_task_context` for the signal you pick — the objects, the verified route between systems, the playbooks, and the operation a rule suggests with your key's policy for it.
3. `ask` or `route` when you need to know where something lives; then read the rows in your human's own systems, with your own credentials.
4. `request_action` before you act in the shop, the ad platform or the helpdesk. Act only on `allowed`; on `pending`, ask again later with the same idempotency key.
5. `record_action` when you are done — with a value only when the shop's own systems state one.

Maplith never returns rows, never performs the action and never holds the credentials you act with. Read the caveats on a join before you rely on it, and say "I could not verify this" rather than guess. More: [For agents](/docs/for-agents).