# Record search events

URL: /docs/api/storefront/search/record-search-events

Reports, in batches of 1–20, what the shopper did with search answers: `settled` (a suggest
answer they stopped at: it becomes a counted search), `click` and `add_to_cart`. Each event
names the answer by its `X-Search-Id`; the engine takes the query and the totals from its own
15-minute record of that answer, so the client never sends query text, counts or anything
personal. Events for an unknown or expired search id, a repeated `settled`, a `settled` for a
results page, or a click on something the answer cannot have shown are dropped silently:
every well-formed batch is `202`. Never retry a failed beacon.

## POST /v1/search/events

```http
POST https://api.elaraone.app/api/v1/search/events
```

Reports, in batches of 1–20, what the shopper did with search answers: `settled` (a suggest
answer they stopped at: it becomes a counted search), `click` and `add_to_cart`. Each event
names the answer by its `X-Search-Id`; the engine takes the query and the totals from its own
15-minute record of that answer, so the client never sends query text, counts or anything
personal. Events for an unknown or expired search id, a repeated `settled`, a `settled` for a
results page, or a click on something the answer cannot have shown are dropped silently:
every well-formed batch is `202`. Never retry a failed beacon.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `X-Client-IP` | header | string |  | Optional. IP address of the shopper (one IPv4/IPv6, no port, no list). Honoured only together with a valid X-Tenant-Secret; ignored otherwise. Used for rate limits and recorded with form submissions. |
| `X-Tenant-Secret` | header | string |  | Optional here. Server secret of the store: server-to-server only, never from a browser. Enables X-Client-IP. |

### Request body (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `events` | object[] | yes | 1–20 events, sent in the order they happened. |

### Responses

- **202**: Success.
- **402**: Payment required. Branch on `error.code`: - `TENANT_PAYMENT_REQUIRED`: this store is on payment hold. Show a "store temporarily unavailable" page; do not retry the request.
- **422**: Validation error
- **429**: `RATE_LIMITED`: per store and shopper IP (`X-Client-IP` with a valid `X-Tenant-Secret`). The batch is dropped: never retry a beacon.