List Connected Offers

Search and list Offers across all connected merchants

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:

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 containing an array of Offer objects.

Filtering Results

The search body accepts optional filters to narrow results:

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

Prices are in the smallest currency unit (e.g., cents). A min_price of 2500 means $25.00 USD.

For the full list of supported filter options, see the Search Offers API Reference.

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 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}
Fetch a single offer by ID	GET /catalog/offers/{offer_id}

Keeping Your Catalog Up to Date

Violet strongly discourages scraping the search endpoint to keep your catalog current. Instead, use Offer Webhooks to receive real-time notifications when Offers are added, updated, or removed.

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

If your filters seem to have no effect, check your casing first. This is the most common cause of unexpected results.

Verify your merchant connections

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

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

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.