# Search Offers

{% hint style="warning" %}
`POST /catalog/offers/search` returns eventually consistent data and is not real-time consistent. Use Offer Search for discovery, then use non-search Offer endpoints (for example, `GET /catalog/offers/{offer_id}`) when you need real-time Offer data.
{% endhint %}

#### Enhanced Search (Beta)

An optional enhanced search mode is available for faster response times and more accurate queries. To use it, pass `beta=true` as a query parameter in your request. This is optional — the endpoint works fully without it.

**What enhanced search adds:**

* Faster response times
* NLP-based search queries
* Enhanced filter criteria

**Current limitations of enhanced search:**

* Returns partial offer data by default (passing `extended=true` will return full data but reduces performance)
* The following search body attributes are not yet supported in enhanced mode:
  * sort\_by
  * sort\_direction

Coming soon to enhanced search:

* Accurately mapped subscription\_status (part of a new Violet feature — for now, you can ignore this value)

## Filtering by Visibility

By default, this endpoint applies no visibility filter and returns all offers. Use the `visible` field in the request body to control this:

| `visible` value | Result                                           |
| --------------- | ------------------------------------------------ |
| omitted         | All offers returned (no filter)                  |
| `true`          | Only offers with `visible=true`                  |
| `false`         | Only offers with `visible=false` (hidden offers) |

### When Offers Have `visible=false`

Offers are marked as hidden (`visible=false`) in the following cases:

* **Stores without a public storefront** - When a Shopify store has no public online store URL configured (common for test stores, development environments, or private stores)
* **Unpublished products** - Products that exist in Shopify but haven't been published to the online storefront (no `publishedAt` date)

**Why this matters:** During offer ingestion, Violet checks whether the merchant's store has a public online store URL. If it doesn't (which is typical for test stores), all offers are marked as `visible=false` by default, since there's no public storefront for customers to view them.

Visibility is determined during offer ingestion based on:

* Whether the merchant has a public online store URL configured in Shopify
* Whether the product is published in Shopify (`publishedAt` date)

### Troubleshooting Empty Results

If you're not seeing any results from the search endpoint, check if the merchant's storefront is public and has products published. You can verify by omitting `visible` from the request body entirely — if results appear, their offers exist but have `visible=false`.

{% openapi src="/files/bEbkEBPLf0IRBDBqq1jM" path="/catalog/offers/search" method="post" expanded="true" %}
[catalog-service.yaml](https://3937396275-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8lXIp71Ct5qCUhXjko2q%2Fuploads%2Fgit-blob-fde56b6f5d9d30a4a0e803aad6d1e17f943adb14%2Fcatalog-service.yaml?alt=media)
{% endopenapi %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/api-reference/catalog/offers/search-offers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.