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

# Supplier portal: insights and alerts

> Show a signed-in supplier their demand and search insights, and build a bell for their new, moved and cancelled bookings from the alerts inbox.

This page is part of [Build a supplier portal](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md).
Paths are relative to `/v1/projects/{projectId}/suppliers/me`. Every call
takes your API key and the supplier's access token. See
[Sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md).

## Demand and search insights

| Method | Path | What it does |
| - | - | - |
| `GET` | `/demand` | Booked, searched and unfilled demand by hour of the week. |
| `POST`, `DELETE` | `/demand/suggestions/{key}/dismiss` | Hide a suggestion for 90 days, or undo that. |
| `GET` | `/search-insights` | How often the supplier was shown, seen and booked from search. |

1. `GET /demand?area=zone&days=30`. `area` is `zone` (the default) or `wider`,
   the zone plus a 15-minute drive. `days` is `30` (the default), `90` or `180`.
   `state` is `ok`, `not_enough_data` (fewer than 20 bookings, and no grid) or
   `no_area`. Each grid covers 06:00 to 22:00 local, in the zone named by
   `window.zone`: 7 rows, where day index 0 is Monday, by 16 hourly columns,
   where index 0 is 06:00.
2. To hide a suggestion, `POST /demand/suggestions/{key}/dismiss` with its
   `key` from the response — for example `open:WED:14:00-16:00`. `DELETE` the
   same path to show it again. Both are idempotent.
3. `GET /search-insights?days=28`. `days` is `7`, `28` (the default) or `90`.
   For a custom range, send `from` and `to` (`YYYY-MM-DD`, at most 365 days)
   instead. `state` is `ok`, or `nothing_yet` when no counted search involved
   the supplier in this window or the one before. A `nothing_yet` response has
   no tiles, missed searches or breakdowns: show an empty state, not zeros.

The business switches each insight on per project. While a switch is off, its
routes answer:

```json theme={null}
{
  "code": "INSIGHTS_DISABLED",
  "message": "Supplier insights (demand) are turned off for this project",
  "statusCode": 403,
  "requestId": "1f6c3b8e-4a2d-4e59-9b07-3d5a8c2e6f41"
}
```

Search insights count only searches your site reported as drawn. See
[Report site events](https://docs.gomarketbox.com/guides/report-site-events.md).

## Alerts

| Method | Path | What it does |
| - | - | - |
| `GET` | `/alerts/summary` | The unread count and the open conditions: what a bell badge needs. |
| `GET` | `/alerts` | The supplier's alerts, newest first. |
| `POST` | `/alerts/{alertId}/read` | Mark one alert read. |
| `POST` | `/alerts/read-all` | Mark the unread alerts read, up to 1,000 per call. |

These are the bell in the MarketBox dashboard: the same alerts, from the same
inbox. Marking one read in your portal clears it in the dashboard too, and the
reverse. The portal always reads the supplier's **own supplier inbox**. Staff
and client alerts never appear here, whatever other roles the person holds.

To build a bell:

1. Poll `GET /alerts/summary` for the badge, **no more often than every 60
   seconds**. The badge is `unreadCount` plus one for each entry in
   `conditions`. When `unreadCapped` is `true` there are 100 or more unread:
   show "99+". The response is `Cache-Control: no-store`.
2. When the supplier opens the panel, call `GET /alerts?filter=unread`, or
   `filter=all` (the default). A page holds up to `limit` alerts (1–100,
   default 20). Follow `nextCursor` until it is `null`.
3. When the supplier opens an alert, `POST /alerts/{alertId}/read`. It answers
   `204`, also when the alert was already read. An id that isn't in this
   supplier's inbox is a `404`, the same answer as an id that doesn't exist.
4. For "Mark all as read", `POST /alerts/read-all`. It answers
   `{ "data": { "updated": 12, "more": false } }`. Call it again while `more`
   is `true`.

A cursor is valid only for the `filter` that produced it. Any other cursor is
refused, so start again from the first page:

```json theme={null}
{
  "code": "INVALID_CURSOR",
  "message": "cursor is not valid for this list. Request the first page again without it.",
  "statusCode": 400,
  "requestId": "2a7d9c41-5e3b-4f18-b6a0-8c1e4d7f2b95"
}
```

**Alerts hold no URL.** Each carries a `target`, which your portal maps to its
own page. The `LESSON_` kind names are fixed identifiers; each is about a
booking.

| `kind` or condition | Suggested copy | `target` | Your page |
| - | - | - | - |
| `LESSON_ASSIGNED` | "New booking" | `{ "kind": "booking", "bookingId" }` | The booking's detail page |
| `LESSON_MOVED` | "Booking moved" | `{ "kind": "booking", "bookingId" }` | The booking's detail page |
| `LESSON_CANCELLED` | "Booking cancelled" | `{ "kind": "booking", "bookingId" }` | The booking's detail page |
| `MY_REPORTS_OVERDUE` | "N bookings need your report" | `{ "kind": "myAppointments", "filter": "awaiting" }` | Your bookings list, filtered to those awaiting a report |

The `kind` and `target.kind` enums also list client and staff values, which a
supplier inbox doesn't receive. Skip any `kind` or `target` your portal doesn't
map, rather than failing on it.

For example, `PAYMENT_NEEDS_REVIEW` is a staff alert. It goes to the
project's admins, never to a supplier inbox. It flags money Stripe has
already moved that needs a person to look at it. Its `target` is
`{ "kind": "order", "orderId" }`, and `payload.paymentReason` says why:

| `paymentReason` | Meaning |
| - | - |
| `DISPUTE_OPENED`, `DISPUTE_WON`, `DISPUTE_LOST` | A chargeback on a card payment opened, or was decided. |
| `PAID_ON_CANCELLED_ORDER` | A card payment succeeded after its order was cancelled. Refunding it is the business's decision. |
| `ORDER_OVERPAID` | Settlement left `amountPaid` above the order's total. |
| `REFUND_FAILED` | Stripe failed a card refund after reporting it succeeded, so the client didn't get the money back. |

A supplier portal never receives this alert. If you validate responses
against strict enums generated from the reference, they now include these
values.

The `payload` holds what the copy needs: `clientName` (shown as the service's
participant settings allow, for example "Jordan L."), `serviceName`, and the
booking's start as `startUtc` with its `zone`. Show the time in that zone. See
[Times](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md#times).

**Conditions are not alerts.** A condition such as `MY_REPORTS_OVERDUE` is
computed on every read. It has no read state, and "Mark all as read" doesn't
clear it. It leaves when the supplier files the reports, and its count can take
up to 5 minutes to catch up. Alerts are kept for 90 days.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.