> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/overview/interact-with-catalogs/list-connected-offers.md).

# List Connected Offers

To retrieve Offers across all merchants you are connected to, use the Search Offers endpoint. This returns paginated results scoped to your channel — you will only see Offers from merchants that have an active connection with your application.

{% 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 when you need real-time Offer data.
{% endhint %}

## Endpoint

```
POST /v1/catalog/offers/search
```

## Basic Request

To list all connected Offers with no filters, send a `POST` request with an empty body:

```bash
curl -X POST https://sandbox-api.violet.io/v1/catalog/offers/search?page=1&size=20 \
  -H "X-Violet-App-Id: your-app-id-here" \
  -H "X-Violet-App-Secret: your-app-secret-here" \
  -H "X-Violet-Token: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The response is a standard [paginated response](https://github.com/violetio/docs/blob/main/concepts/pagination.md) containing an array of Offer objects.

## Filtering Results

The search body accepts optional filters to narrow results:

```json
{
  "query": "sneakers",
  "min_price": 2500,
  "max_price": 15000,
  "available": true
}
```

{% hint style="info" %}
Prices are in the smallest currency unit (e.g., cents). A `min_price` of `2500` means $25.00 USD.
{% endhint %}

For the full list of supported filter options, see the [Search Offers API Reference](https://github.com/violetio/docs/blob/main/api-reference/catalog-service/catalog-offers/search-offers.md).

## Currency Conversion

Pass the `base_currency` query parameter to receive prices in your preferred currency. The default is USD.

```
POST /v1/catalog/offers/search?base_currency=GBP
```

All prices in the response will reflect the specified currency.

## Enhanced Search (Beta)

An optional enhanced search mode provides faster response times and NLP-based querying. To enable it, pass `beta=true` as a query parameter:

```
POST /v1/catalog/offers/search?beta=true
```

See the [Search Offers API Reference](https://github.com/violetio/docs/blob/main/api-reference/catalog-service/catalog-offers/search-offers.md) for current capabilities and limitations of enhanced search.

## When to Use This vs. Get Merchant Offers

| Use Case                                            | Endpoint                                                                                                             |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Browse or search across **all** connected merchants | `POST /catalog/offers/search`                                                                                        |
| List offers from a **specific** merchant            | [`GET /catalog/offers/merchants/{merchant_id}`](/prism/overview/interact-with-catalogs/get-offers-for-a-merchant.md) |
| Fetch a **single** offer by ID                      | `GET /catalog/offers/{offer_id}`                                                                                     |

## Keeping Your Catalog Up to Date

{% hint style="info" %}
Violet **strongly** discourages scraping the search endpoint to keep your catalog current. Instead, use [Offer Webhooks](/prism/webhooks/events/offer-webhooks.md) to receive real-time notifications when Offers are added, updated, or removed.
{% endhint %}

**Recommended pattern:**

1. Perform an initial pull using this endpoint to populate your catalog
2. Subscribe to `OFFER_AVAILABLE`, `OFFER_UPDATED`, and `OFFER_REMOVED` webhooks
3. Use the [Get Offer by ID](https://github.com/violetio/docs/blob/main/api-reference/catalog-service/catalog-offers/get-offer-by-id.md) endpoint to fetch full details when a webhook fires

This approach keeps your catalog current without unnecessary API calls.

## Troubleshooting: Empty Results

If your search returns an empty `content` array regardless of what filters you use, the issue is usually with **your connections** — not your search parameters. The endpoint returns `200 OK` with empty content when there are no matching offers, which can be misleading.

### Check your parameter casing

The Violet API uses **snake\_case** for all request body parameters. Unrecognized parameters are silently ignored, so camelCase variants won't cause an error — they simply have no effect.

| Incorrect (camelCase) | Correct (snake\_case) |
| --------------------- | --------------------- |
| `merchantId`          | `merchant_id`         |
| `minPrice`            | `min_price`           |
| `maxPrice`            | `max_price`           |

{% hint style="warning" %}
If your filters seem to have no effect, check your casing first. This is the most common cause of unexpected results.
{% endhint %}

### Verify your merchant connections

Check whether your app is connected to any merchants in the environment you're testing against:

```bash
curl -X GET https://sandbox-api.violet.io/v1/merchants \
  -H "X-Violet-App-Id: your-app-id-here" \
  -H "X-Violet-App-Secret: your-app-secret-here" \
  -H "X-Violet-Token: your-token-here"
```

If this returns an empty list, you have no active merchant connections in this environment.

### Check your environment

Merchant connections are **environment-specific**. A merchant connected in live mode is not automatically connected in sandbox, and vice versa. Make sure you're querying the same environment where your merchants are connected (`sandbox-api.violet.io` vs `api.violet.io`).

{% hint style="info" %}
**New to sandbox?** All sandbox applications come pre-connected to Violet's demo merchants. If `GET /merchants` returns demo merchants but offer search is still empty, the demo catalog may still be syncing. Try filtering by one of the demo merchant IDs using `GET /catalog/offers/merchants/{merchant_id}` to confirm.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/prism/overview/interact-with-catalogs/list-connected-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.