Offer Search
POST /catalog/offers/search
Returns a page of Offers
that match a specified query.
Request Parameters
*Only available in beta
Query string that performs a fuzzy search against all items you have access to, given additional filter criteria.
Example: storm trooper
Search criteria that specifically searches against the names of an offer.
Example: Star Wars
Filter criteria that matches against whether or not an offer is available.
Example: true
Filter criteria against a list of given merchant_ids. Input is a list of integers.
Example: [10010, 10098]
Filter criteria against a list of given tags associated with offers. Input is a list of integers.
Note: Tags are controlled by e-com platforms.
Example: [”madebygenai”, “kids”]
Filter criteria that matches against whether or not an offer is visible.
Example: false
Filter criteria that matches against the seller of an offer.
Example= nordstrom
Filter criteria that matches against the vendor of an offer.
Example: nike
Range criteria that sets a maximum price in scents search results can have.
Example: 10000
Range criteria that sets a minimum price in cents search results can have.
Example: 1000
Property to sort results by. Must be specified in Camel Case.
Example: maxPrice
Direction of sorted results. Ascending (asc) or descending (desc).
Example: asc
Filter criteria that matches against whether or not an offer has been subscribed to by your app.
Example: SUBSCRIBED
Filter criteria that matches against whether or not a merchant has published an offer
Example:PUBLISHED
Query Parameters
Page to search offers from. Used for pagination of data.
Example: 1
Number of items to return on a single page
Example: 50
Denotes whether or not to use “beta” mode for Offer Search. This allows for faster, optimized queries.
Note: beta requires query
to be passed in as a part of the request body.
Example: true
Denotes whether or not to pull the full Offer data or an optimized subset.
Note: Increased latencies for this request and beta mode required.
Example: true
Sample Request
curl -X POST https://sandbox-api.violet.io/v1/catalog/offers/search?beta=true \
-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 '{"query": "flower shirt"}'
Sample Response
{
"content": [
{
"id": 16908,
"name": "Soy Candle",
"description": "Inspired by gardens and the desert, Form candles are made with hand-poured soy wax. Clean burning and peaceful, once the candle is spent, the vessel becomes a planter!<br><ul><li>Once the candle has burned down, just flip the lid to the bottom to catch water, and add your favorite plant.</li></ul>",
"seller": "Violet",
"merchant_id": 10142,
"available": true,
"min_price": 3499,
"max_price": 3499,
"currency": "USD",
"variants": [],
"skus": [
{
"id": 50039,
"offer_id": 16908,
"merchant_id": 10142,
"external_id": "62005056694338013db7e539",
"name": "Soy Candle",
"in_stock": true,
"inventory_tracked": true,
"taxable": true,
"tax_type": "DEFAULT",
"albums": [],
"variant_values": [],
"status": "AVAILABLE"
}
],
"albums": [],
"three_denabled": false,
"status": "AVAILABLE",
"publishing_status": "PUBLISHED",
"default_image_url": "https://cdn.schema.io/violet/62004fcd544098013eb779ae/8e8147108abcf19be300e8981cb960a8",
"subscription_status": "NOT_SUBSCRIBED",
"tags": [
"candles"
]
}
],
"pageable": {
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"page_number": 0,
"page_size": 20,
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"total_pages": 1,
"total_elements": 1,
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"first": true,
"number_of_elements": 3,
"size": 20,
"number": 0,
"empty": false
}
✨ Beta mode now available ✨
Note: Violet has not fully rolled out support for this feature and it is still in early release. Features below may change.
Beta mode uses an enhanced search work flow for faster response times and more accurate queries. To use beta mode, you can pass in beta=true
as a query parameter in your request.
Enhancements
- Faster response times
- NLP-based search queries
- Enhanced filter criteria
Limitations
- Partial offer data responses (Using
extended=true
in query parameters to extend this data will reduce performance). - The following search criteria(search body attribute) do not yet work with the
beta
flag:sort_by
sort_direction
Upcoming Enhancements
- Accurately mapped subscription_status. This is a part of a new Violet feature. For now, you can ignore the value assigned here.