# 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.

## 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}`](https://docs.violet.io/prism/overview/interact-with-catalogs/get-offers-for-a-merchant) |
| 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](https://docs.violet.io/prism/webhooks/events/offer-webhooks) 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 %}