---
title: "Integrations and automations"
description: "Set up a store's integrations and automations over MCP, and what happens to them when a connection ends."
---

> 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.

# Integrations and automations

Integrations send a store's data to services it works with. Automations act on their own when something happens in the store. Both need the `integration` and `automation` scopes, which only the Everything set holds (see [Scopes](/merchant-mcp/scopes)).

## Integrations

[`list_integrations`](/merchant-mcp/tools/list_integrations) (`integration:read`) lists every integration the store can use, under `result`. Read the list from there: which integrations exist, and what each takes, is in its answer. Each one has:

- `id`, `name`, `description` and `kind`;
- `enabled`: whether it is on;
- `sets_cookies`: whether its page tags set cookies in a visitor's browser, so turning it on shows the storefront's cookie banner to visitors where the law asks for consent;
- `config_schema`: a JSON Schema of its settings, where `secret: true` marks a secret and `default` suggests a value (it is never filled in for you);
- `config`: its current settings, without secrets;
- `secret_set`: which secrets are set;
- `connection_ended_at`: when the connection that set it up ended, or null.

To send a store's events to an endpoint of your own, add a webhook endpoint with [`create_webhook`](/merchant-mcp/tools/create_webhook) instead (see [Webhooks](/merchant-mcp/webhooks)).

[`set_integration`](/merchant-mcp/tools/set_integration) (`integration:write`) takes the integration as `{ "id": "..." }`, a `config` and `enabled`:

- Leave `config` out to keep the stored settings, for example to only turn it on or off.
- A secret left out of `config` keeps its stored value, and a secret set to `null` is cleared.
- A key `config_schema` doesn't declare is refused as `invalid`, with the reason "not declared".
- A text value is at most 2,000 characters.
- A value the storefront places in the integration's page tags is read without surrounding spaces, and may hold only letters, digits, `_`, `+` and `-` (a value in a script's address also `/`). Any other is refused as `invalid`, with the reason "not usable in its tags", when you set it or turn the integration on. A secret never goes in a page, so this never applies to one.
- Turning one on needs every key its schema requires, or it is `invalid` with the reason "required". A required key with a `default` still needs its value in `config`.
- For one that sends buyer and order data, turning it on, or changing the settings that say where it sends them (even while it is off), needs the read scopes of the `order.created` webhook event (see [Webhooks](/merchant-mcp/webhooks#events)). Without them, the call answers HTTP `403` with `insufficient_scope`.

It answers the integration as `list_integrations` lists it, without its `config`.

### When the connection ends

An integration belongs to a connection. A connection becomes its owner when it sets it up first, when it sends a `config` other than null, or when it turns it on after the connection that owned it ended. Turning it on or off without a `config` otherwise leaves the owner as it is. When that connection is revoked, expires or loses the access the integration needs, the integration is turned off and its secrets are dropped, and `connection_ended_at` says when. To use it again, set its secrets and turn it on with `set_integration`.

## Automations

An automation is a rule: when its trigger happens, it runs its action for the customer it happened to.

| Tool | Scope |
| --- | --- |
| [`list_all_automations`](/merchant-mcp/tools/list_all_automations), [`get_automation`](/merchant-mcp/tools/get_automation), [`list_automation_runs`](/merchant-mcp/tools/list_automation_runs) | `automation:read` |
| [`create_automation`](/merchant-mcp/tools/create_automation), [`update_automation`](/merchant-mcp/tools/update_automation), [`pause_automation`](/merchant-mcp/tools/pause_automation), [`resume_automation`](/merchant-mcp/tools/resume_automation) | `automation:write` |
| [`delete_automation`](/merchant-mcp/tools/delete_automation) | `automation:delete` |

[`create_automation`](/merchant-mcp/tools/create_automation) takes a `trigger`, an `action` and, optionally, a `name` of up to 200 characters. Each of `trigger` and `action` names its `kind`.

### Triggers

- `product.purchased`: a customer buys `product`. Optionally narrowed to one of its prices, `price`, or to a discount code, `discount`.
- `product.reviewed`: a customer reviews `product`. Optionally only at `min_rating` or above, from 1 to 5.
- `event.checked_in`: a customer is checked in at an event, `product`. Optionally only at one of its sessions, `session`, as `{ "id": "..." }`. See [Automations on check-in](/merchant-api/guides/event-check-in#automations-on-check-in).

`product` is `{ "id": "..." }` or `{ "slug": "..." }`. An `event.checked_in` trigger's `product` must be an event, else it's a `conflict` on `category`, and its `session` one of that event's. A trigger needs `product:read`, plus `price:read` or `discount:read` when it names a price or a discount.

### Actions

- `product.unlock`: gives the customer access to `product`. Needs `customer:write` and `product:read`.
- `price.adjust`: makes the customer a single-use discount code, for them alone, off `price`. It takes `fixed_cents`, `variable_percent` (0 to 100) or both, and optionally a `window` with `starts_at` and `ends_at`. Each code made sends a `discounts.unlocked` event. Needs `discount:write` and `price:read`.

Without a scope it needs, the call answers HTTP `403` with `insufficient_scope`.

```json
{
  "name": "Thank-you discount",
  "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" }
  }
}
```

[`update_automation`](/merchant-mcp/tools/update_automation) changes its `name`, `trigger` or `action`. A new trigger or action needs the scopes creating it would. [`pause_automation`](/merchant-mcp/tools/pause_automation) stops it until [`resume_automation`](/merchant-mcp/tools/resume_automation), and [`delete_automation`](/merchant-mcp/tools/delete_automation) removes it. Resuming needs the action's own scope too: `customer:write` for `product.unlock`, `discount:write` for `price.adjust`. Pausing a paused automation, or resuming a running one, is a `conflict` with `{ "field": "status", "current": "paused" }` or `"running"`.

A store holds at most 200 automations. Past that, `create_automation` is a `conflict`.

### Runs

Each time a trigger happens, the automation runs once. A `product.reviewed` rule runs once per reviewer, and an `event.checked_in` rule once per customer, whichever session lets them in and however often. [`list_automation_runs`](/merchant-mcp/tools/list_automation_runs) lists runs, filtered by `automation_id`, `status`, `trigger_kind` or `occurred_at`. A run's `status` is:

- `pending`: not run yet.
- `succeeded`: done; `result` names what it made, such as the grant or the discount.
- `skipped`: nothing to do, with `reason` saying why: `paused`, `rule changed`, `customer gone`, `trigger gone`, `trigger changed`, `product gone`, `category unknown`, `product is repeatable`, `already entitled`, `price gone`, `takes nothing off`, `window over` or `unlocks paused`.
- `failed`: it failed, with `reason` set to `error`.

Runs are kept for 92 days. Pending runs, and runs of a `product.reviewed` or `event.checked_in` trigger that weren't skipped, are kept past that.

### When the connection ends

Automations a connection created keep running after it is revoked, expires or is removed from the business, until they are paused. The Connections page lists what a connection made in each business it reached, under **What it made or changed in** that business, so you can pause them there. For a connection made before connections could reach several businesses, the API tokens page lists them. An app can also read each automation's `token_id`, the token of the connection that created it in that business.

## Redirects

The store's redirects are set up with [`create_redirect`](/merchant-mcp/tools/create_redirect), [`update_redirect`](/merchant-mcp/tools/update_redirect) and [`delete_redirect`](/merchant-mcp/tools/delete_redirect), listed with [`list_redirects`](/merchant-mcp/tools/list_redirects), and [`check_path`](/merchant-mcp/tools/check_path) says whether a path is free.

| Tool | Scope |
| --- | --- |
| `list_redirects` | `site:read` |
| `create_redirect`, `update_redirect` | `site:write` |
| `delete_redirect` | `site:delete` |
| `check_path` | `site:read`, plus the scope of the `kind` it checks: `product:read` for `product`, `custompage:read` for `page`, `site:read` for `redirect` |

Like an integration, a redirect a connection set up is turned off when that connection ends, with `connection_ended_at` saying when.

Source: https://docs.sherpo.io/merchant-mcp/integrations-and-automations/index.mdx
