📘

Cache — Cache-Control: public, max-age=3600 (1 hour)

Part of the catalog — The product catalog explains how merchants, products, calendars and timeslots fit together.

Why this endpoint exists

This is the search box on your storefront. The customer types "zoo" or "amsterdm" and expects results, so the match is deliberately broad: it runs across merchant name, alias and description, and tolerates imprecise input.

That forgiveness is the trade-off. Broad search casts wide and ranks by relevance; it will surface a merchant whose description mentions zoos even if its name does not. When you need precision — field weighting, or "near me" — use custom search instead.

How to use it

curl "https://api.acc.funtrips.io/v2/merchants/broadsearch?query=zoo&limit=20" \
  -H "x-campaign-id: 3c1e5a90-7b2d-4f61-9a83-1d4e7f2b8c05" \
  -H "Accept-Language: nl-NL"

The response is a list of Merchant objects, identical in shape to list merchants.

Query parameters

limit is not optional in practice

🚧

Omit limit and you get every match in a single response, with no meta.pagination block.

Against a large catalog and a vague query that is a slow, enormous payload — and the endpoint's realistic failure mode is a 504 while your customer watches a spinner. Always send limit.

Send it and you get a normal paginated response. Treat unpaginated mode as a convenience for scripts, never as a storefront code path.

Debouncing

Search fires on keystrokes, and each keystroke is a request. Debounce by 250–300 ms and cancel in-flight requests when the query changes. There is no server-side rate limit on this endpoint today, but an undebounced search box is a wasteful pattern that will surface as latency for your own users first.

Errors

504 is retryable and is the one to expect with no limit on a broad query. Retry once with a limit rather than retrying the same unbounded request — otherwise you will simply time out again.

No matches is 200 with an empty array, not 404. Render "no results", not an error.