---
title: "Examples"
description: "Worked calls to the merchant MCP server, with what each answers."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

These examples show the arguments a client sends and what the server answers. An MCP client builds the JSON-RPC messages itself, so most show only `params` and the result. Records in answers are trimmed to the fields that matter: each tool's page has the whole answer.

## A raw call over HTTP

A `tools/call` on the 2026-07-28 protocol, sent to `https://mcp.sherpo.io` (the `/mcp` path works the same). The access token comes from [signing in](/merchant-mcp/sign-in).

Every request sends `MCP-Protocol-Version` and `Mcp-Method`, and a `tools/call` also sends `Mcp-Name`, matching the body's `name`. In `params._meta`, `protocolVersion` and `clientCapabilities` are required, and `clientInfo` is optional. `Accept` is needed only on the 2025-era path, which must send `Accept: application/json, text/event-stream` (see [Connect your agent](/merchant-mcp/connect#any-other-mcp-client)).

```http
POST /mcp HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_products
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_products",
    "arguments": { "query": { "limit": 1 } },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}
```

The answer is JSON, with the result as `structuredContent` and the same JSON as text:

```http
HTTP/1.1 200 OK
Content-Type: application/json
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"items\":[{\"id\":\"9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80\",\"slug\":\"intro-course\",\"title\":\"Intro course\",\"status\":\"published\"}],\"cursor\":\"Kq7vX2mPzR4tB9wNc3Ld\"}"
      }
    ],
    "structuredContent": {
      "items": [
        {
          "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
          "slug": "intro-course",
          "title": "Intro course",
          "status": "published"
        }
      ],
      "cursor": "Kq7vX2mPzR4tB9wNc3Ld"
    }
  }
}
```

A call without a valid token answers `401` instead, and one the connection lacks the scope for answers `403`. See [Errors](/merchant-mcp/errors#http-statuses).

## Listing and paging

The published courses, newest first, two at a time, with the total:

```json
{
  "name": "list_products",
  "arguments": {
    "query": {
      "filter": { "status": "published", "category": "course" },
      "sort": { "name": "created", "direction": "desc" },
      "limit": 2,
      "count": true
    }
  }
}
```

```json
{
  "items": [
    {
      "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
      "slug": "intro-course",
      "title": "Intro course",
      "category": "course",
      "status": "published",
      "created_at": "2026-10-28T09:12:00.000Z"
    },
    {
      "id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
      "slug": "spring-workshop",
      "title": "Spring workshop",
      "category": "course",
      "status": "published",
      "created_at": "2026-09-14T16:40:00.000Z"
    }
  ],
  "cursor": "Wf8sJ1nQ6yHk0eUa5ZrT",
  "total": 3
}
```

The next page sends the same `query` with the `cursor`:

```json
{
  "name": "list_products",
  "arguments": {
    "query": {
      "filter": { "status": "published", "category": "course" },
      "sort": { "name": "created", "direction": "desc" },
      "limit": 2,
      "cursor": "Wf8sJ1nQ6yHk0eUa5ZrT"
    }
  }
}
```

```json
{
  "items": [
    {
      "id": "17c4d9e2-8a3b-4f60-b1d7-5e9a2c0f4b38",
      "slug": "pottery-basics",
      "title": "Pottery basics",
      "category": "course",
      "status": "published",
      "created_at": "2026-06-02T11:05:00.000Z"
    }
  ],
  "cursor": null
}
```

A null `cursor` is the last page. The cursor is opaque: pass it back as it is.

## Naming the store

A connection reaching two stores names one in every store tool:

```json
{ "name": "get_store", "arguments": { "store": "a7f2c915-4e8b-4d36-b0a1-8c5e3f9d2b47" } }
```

```json
{
  "id": "a7f2c915-4e8b-4d36-b0a1-8c5e3f9d2b47",
  "name": "Clay studio",
  "currency": "EUR",
  "time_zone": "Europe/Rome"
}
```

Without `store`, the same call is a tool error:

```json
{
  "isError": true,
  "content": [{ "type": "text", "text": "An argument is malformed. At [\"store\"]: required. (invalid)" }],
  "structuredContent": {
    "code": "invalid",
    "context": { "path": ["store"], "reason": "required" }
  }
}
```

## How a launch did

To see how a product launched on 1 November did in its first week, read [`product_traffic_stats`](/merchant-mcp/tools/product_traffic_stats) for the week, which also answers the week before:

```json
{
  "name": "product_traffic_stats",
  "arguments": {
    "product": { "slug": "spring-workshop" },
    "from": "2026-11-01",
    "to": "2026-11-07"
  }
}
```

```json
{
  "time_zone": "Europe/Rome",
  "from": "2026-11-01",
  "to": "2026-11-07",
  "previous_range": { "from": "2026-10-25", "to": "2026-10-31" },
  "rolled_through": "2026-11-14",
  "covered_from": "2026-10-20",
  "product_views": { "current": 1840, "previous": 95 },
  "checkouts_started": { "current": 212, "previous": 4 },
  "orders": { "current": 61, "previous": 1 },
  "rates": {
    "current": { "view_to_checkout": 0.1152, "checkout_to_order": 0.2877, "view_to_order": 0.0332 },
    "previous": { "view_to_checkout": 0.0421, "checkout_to_order": 0.25, "view_to_order": 0.0105 }
  },
  "estimated": false,
  "visitors": { "current": 1210, "previous": 71 },
  "by_channel": [
    { "channel": "web", "views": { "current": 1702, "previous": 95 }, "visitors": { "current": 1133, "previous": 71 }, "estimated": false },
    { "channel": "mcp", "views": { "current": 138, "previous": 0 }, "visitors": { "current": 77, "previous": 0 }, "estimated": false }
  ]
}
```

`visitors` are each day's unique visitors added up, since no visitor is followed from one day to the next. `rolled_through` is the last day counted: later days count nothing yet, and a span before `covered_from` answers its figures as `null`. [`traffic_stats`](/merchant-mcp/tools/traffic_stats) and [`conversion_stats`](/merchant-mcp/tools/conversion_stats) answer the same for the whole store, by channel, country and product.

## What a customer would pay

To check what a customer would be charged for a course with a code before announcing it, call [`simulate_checkout`](/merchant-mcp/tools/simulate_checkout). It buys nothing and uses no coupon:

```json
{
  "name": "simulate_checkout",
  "arguments": {
    "customer": { "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918" },
    "product": { "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42" },
    "coupon": "SPRING10"
  }
}
```

```json
{
  "at": "2026-11-16T10:30:00.000Z",
  "customer": { "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918" },
  "product": { "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42" },
  "coupon": "SPRING10",
  "quantity": 1,
  "owned": null,
  "prices": [
    {
      "price": { "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d", "tier": { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "rank": 1, "name": "Course" }, "kind": "one_time", "period": null, "title": null, "currency": "eur", "exponent": 2, "amount": 4900 },
      "verdict": { "status": "charged", "mode": "purchase", "unit": 4410, "quantity": 1, "total": 4410 },
      "mode": "purchase",
      "list": 4900,
      "discounted": 4410,
      "discount": { "applied": "coupon", "automatic": null, "coupon": { "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8", "name": "Spring sale", "code": "SPRING10", "discounted": 4410 } },
      "coupon": { "status": "applied" },
      "upgrade": null,
      "minimum": { "amount": 50, "approximate": false, "waived": null },
      "recurring": null
    }
  ]
}
```

Leave `customer` out to price for a new customer. Naming a customer needs `customer:read`, and a coupon `discount:read`. A refused price answers `"verdict": { "status": "refused", "reason": ... }`, and `coupon.status` says why a code doesn't apply. [Simulate an order](/merchant-api/guides/simulate-an-order) explains every field.

## A conflict

Publishing a product that is already published:

```json
{ "name": "publish_product", "arguments": { "product": { "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80" } } }
```

```json
{
  "isError": true,
  "content": [{ "type": "text", "text": "The call clashes with the current state. (conflict)" }],
  "structuredContent": {
    "code": "conflict",
    "context": { "field": "status", "current": "published" }
  }
}
```

The product is already as the call wanted, so there is nothing to retry. `context.current` is its status now.

## Seeing a body rendered

Reading a page's draft:

```json
{ "name": "read_body", "arguments": { "target": { "kind": "page", "id": "4f1c9a2e-7b3d-4e60-a8f5-2c9d0b6e1a73" }, "staged": true } }
```

The store's home is read the same way, with `{ "kind": "store" }` as the target.

```json
{
  "attachment": { "id": "8d2a6f13-5c4e-4b97-9e0a-1f7c3b5d2e86" },
  "asset": { "id": "c3e7b1a9-2f6d-4085-b4c2-9a1e5d7f3b20" },
  "mime": "application/vnd.sherpo.blocks+json",
  "content": "{\"blocks\":[…]}",
  "files": { … },
  "preview": {
    "url": "https://…/about?preview=…",
    "expires_at": "2026-11-03T15:30:12.000Z"
  }
}
```

`preview.url` opens the page as a visitor sees it, draft included, until `expires_at` and with no sign-in, so it can be opened in a browser or a headless renderer, at desktop and phone widths and in light and dark, to check how it looks. [`set_body`](/merchant-mcp/tools/set_body) answers one too. [Previews](/merchant-api/rich-text#previews) says what a link opens and when it is null.

## Bulk, with one item refused

Deleting two products, one of which doesn't exist:

```json
{
  "name": "bulk",
  "arguments": {
    "accessor": "deleteProduct",
    "items": [
      { "product": { "id": "17c4d9e2-8a3b-4f60-b1d7-5e9a2c0f4b38" } },
      { "product": { "id": "0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65" } }
    ]
  }
}
```

The call succeeds. Its first text says how many items were refused, and `results` holds one outcome per item, in order:

```json
{
  "content": [
    { "type": "text", "text": "1 of 2 items refused." },
    {
      "type": "text",
      "text": "{\"results\":[{\"outcome\":\"done\"},{\"outcome\":\"refused\",\"error\":{\"code\":\"not_found\",\"detail\":{\"kind\":\"product\",\"ref\":{\"id\":\"0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65\"}}}}]}"
    }
  ],
  "structuredContent": {
    "results": [
      { "outcome": "done" },
      {
        "outcome": "refused",
        "error": {
          "code": "not_found",
          "detail": { "kind": "product", "ref": { "id": "0d6b3e81-5f2a-4c97-a4e8-9b1c7f3d2a65" } }
        }
      }
    ]
  }
}
```

## A webhook

Create an endpoint for new orders. The connection needs the Everything set, and the read scopes of `order.created`:

```json
{
  "name": "create_webhook",
  "arguments": {
    "url": "https://hooks.example.com/sherpo",
    "events": ["order.created"]
  }
}
```

```json
{
  "webhook": {
    "id": "8e4b1d27-6c3a-4f90-b2e5-0a7d9c1f3e68",
    "url": "https://hooks.example.com/sherpo",
    "description": null,
    "events": ["order.created"],
    "enabled": true,
    "connection_ended_at": null,
    "created_at": "2026-11-03T14:02:11.000Z",
    "updated_at": "2026-11-03T14:02:11.000Z"
  },
  "secret": "whsec_Qm3vT8kZp1rXw7Lc2nYb5dHs0aGf4eJu"
}
```

Keep the `secret`: no call answers it again. Each delivery then carries a `Sherpo-Signature` header such as:

```text
Sherpo-Signature: t=1793715637,v1=5f1c0e9a7b3d2c4e6f8a1b0c9d7e5f3a2b4c6d8e0f1a3b5c7d9e2f4a6b8c0d1e
```

Check it against the raw body with the `verifyWebhook` function from [Webhooks](/merchant-mcp/webhooks#verifying-the-signature), then act on the event once per `id`:

```js
const body = await request.text();
const signature = request.headers.get('Sherpo-Signature') ?? '';
if (!(await verifyWebhook(env.SHERPO_WEBHOOK_SECRET, body, signature)))
  return new Response('Bad signature', { status: 400 });
const event = JSON.parse(body);
// Record event.id so a repeated delivery changes nothing.
return new Response(null, { status: 204 });
```

## Uploading a file

A 480 KB PDF for a private download, in three steps.

1. **Step 1**

   Reserve the file:

   ```json
   {
     "name": "create_upload",
     "arguments": {
       "enforcement": "signed",
       "name": "workbook",
       "title": "Workbook",
       "mime": "application/pdf",
       "bytes": 482113
     }
   }
   ```

   ```json
   {
     "asset": {
       "id": "3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73",
       "name": "workbook",
       "title": "Workbook",
       "mime": "application/pdf",
       "bytes": 482113,
       "enforcement": "signed",
       "status": "pending"
     },
     "upload": {
       "url": "https://…",
       "method": "PUT",
       "headers": { "content-type": "application/pdf", "content-length": "482113" },
       "expires_at": "2026-11-03T14:21:00.000Z"
     }
   }
   ```

   `upload.headers` is trimmed here: send every header it lists.
2. **Step 2**

   Send the bytes, before `expires_at`:

   ```http
   PUT <upload.url>
   Content-Type: application/pdf
   Content-Length: 482113

   <the file's bytes>
   ```
3. **Step 3**

   Mark it done:

   ```json
   { "name": "complete_upload", "arguments": { "asset": { "id": "3c9a1f60-7b2d-4e85-a0c4-6d8e2f1b9a73" } } }
   ```

   It answers the file. Attach it where it belongs, for example with [`attach_asset`](/merchant-mcp/tools/attach_asset).

## A discount after a purchase

Give every buyer of the intro course 20% off the workshop's price for the rest of the year:

```json
{
  "name": "create_automation",
  "arguments": {
    "name": "Workshop discount for course buyers",
    "trigger": { "kind": "product.purchased", "product": { "slug": "intro-course" } },
    "action": {
      "kind": "price.adjust",
      "price": { "id": "c41e8b2a-9d07-4f3c-8a65-3b0f7e2d1c94" },
      "variable_percent": 20,
      "window": { "starts_at": "2026-11-03T00:00:00Z", "ends_at": "2026-12-31T23:59:59Z" }
    }
  }
}
```

The connection needs `automation:write`, `discount:write`, `price:read` and `product:read`. It answers the automation:

```json
{
  "id": "6f1d8a3c-2e9b-4c75-b0a4-1d7e5c3f9b28",
  "name": "Workshop discount for course buyers",
  "trigger": {
    "kind": "product.purchased",
    "product_id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
    "price_id": null,
    "discount_id": null,
    "product": {
      "id": "9b2e7c41-0d3f-4a8e-b6c5-1f7a2d9e3b80",
      "slug": "intro-course",
      "path": "/p/intro-course",
      "url": "https://shop.example.com/p/intro-course",
      "title": "Intro course",
      "category": "course",
      "deleted": false
    }
  },
  "action": {
    "kind": "price.adjust",
    "price_id": "c41e8b2a-9d07-4f3c-8a65-3b0f7e2d1c94",
    "product_id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
    "fixed_cents": null,
    "variable_percent": 20,
    "window": { "starts_at": "2026-11-03T00:00:00.000Z", "ends_at": "2026-12-31T23:59:59.000Z" },
    "product": {
      "id": "e5a83f19-2c6d-4b07-9f1e-7d4c0a8b2e56",
      "slug": "spring-workshop",
      "path": "/p/spring-workshop",
      "url": "https://shop.example.com/p/spring-workshop",
      "title": "Spring workshop",
      "category": "course",
      "deleted": false
    }
  },
  "paused_at": null,
  "token_id": "b7d40e2c-9a15-4f83-8c6e-2f0a1d9b5e47",
  "created_at": "2026-11-03T14:30:12.000Z",
  "ended": false
}
```

`token_id` is the token of the connection that created it, in this store's business, and `ended` turns true once a `price.adjust` window is over.

From then on, each purchase of the course makes the buyer a single-use code for the workshop, and sends `discounts.unlocked`. [`list_automation_runs`](/merchant-mcp/tools/list_automation_runs) shows each run and its outcome.

## Move an event from Luma

With Luma's own MCP server connected beside this one, your AI can read an event there and recreate it here: the product with [`create_product`](/merchant-mcp/tools/create_product), its session with [`create_event_session`](/merchant-mcp/tools/create_event_session), its ticket types with [`create_tier`](/merchant-mcp/tools/create_tier) and [`create_price`](/merchant-mcp/tools/create_price), its questions with [`create_product_question`](/merchant-mcp/tools/create_product_question), then each guest going with [`record_order`](/merchant-mcp/tools/record_order), by their email, and their answers with [`set_customer_answers`](/merchant-mcp/tools/set_customer_answers). [Migrate from Luma](/overview/migrate-from-luma#with-your-ai) has a request to start from and what guests receive.

Source: https://docs.sherpo.io/merchant-mcp/examples/index.mdx
