Search Offers
Retrieve a list of Offer's that match a set of filter criteria. These Offers are limited to the Merchants that you are connected to.
✨ Beta mode now available ✨
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=truein query parameters to extend this data will reduce performance).The following search criteria(search body attribute) do not yet work with the
betaflag:sort_bysort_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.
Maximum size limit of 100 results.
Query parameters
pageinteger · int32OptionalDefault:
1sizeinteger · int32OptionalDefault:
20exclude_publicbooleanOptionalDefault:
trueexclude_hiddenbooleanOptionalDefault:
trueextendedbooleanOptionalDefault:
falsebetabooleanOptionalDefault:
falseHeader parameters
X-Violet-TokenstringRequired
X-Violet-App-SecretstringRequired
X-Violet-App-Idinteger · int32Required
Body
Offer Search Request
querystringOptional
Used with the beta flag. A NLP-based search query
visiblebooleanOptional
Filter by visible offers
availablebooleanOptional
Filter by available offers
idinteger · int64Optional
merchant_idinteger · int32Optional
sellerstringOptional
Name of Merchant Selling Product
vendorstringOptional
Name of Original Vendor (Brand)
product_idstringOptional
The parent/container product ID
external_idstringOptional
External ID
namestringOptional
Name of Product in Offer
publishing_statusstring · enumOptionalPossible values:
Publishing status
subscription_statusstring · enumOptionalPossible values:
Subscription status
statusstring · enumOptionalPossible values:
Offer status
source_category_namestringOptional
Offer category from ecom-platform
tagsstring[]Optional
Tags to search for
merchant_idsinteger · int32[]Optional
Merchant Ids to filter by
min_priceinteger · int32Optional
Minimum Price
max_priceinteger · int32Optional
Maximum Price
sort_bystringOptional
Property to sort by in camelCase
sort_directionstringOptional
Direction to sort by
Responses
default
default response
application/json
post
POST /v1/catalog/offers/search HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 390
{
"query": "text",
"visible": true,
"available": true,
"id": 1,
"merchant_id": 1,
"seller": "text",
"vendor": "text",
"product_id": "text",
"external_id": "text",
"name": "text",
"publishing_status": "NOT_PUBLISHED",
"subscription_status": "NOT_SUBSCRIBED",
"status": "UNAVAILABLE",
"source_category_name": "text",
"tags": [
"text"
],
"merchant_ids": [
1
],
"min_price": 1,
"max_price": 1,
"sort_by": "text",
"sort_direction": "text"
}default
default response
{
"content": [
{
"id": 1,
"external_id": "text",
"external_url": "text",
"name": "text",
"description": "text",
"source": "OTHER",
"seller": "Foot Locker",
"vendor": "Nike",
"merchant_id": 1,
"available": true,
"visible": true,
"min_price": 1,
"max_price": 1,
"currency": "text",
"external_currency": "text",
"source_category_name": "text",
"metadata": [
{
"version": 1,
"type": "STRING",
"external_type": "text",
"key": "text",
"value": {},
"external_id": "text",
"source": "INTERNAL"
}
],
"variants": [
{
"id": 1,
"external_id": "text",
"name": "text",
"visual": true,
"values": [
{
"id": 1,
"product_variant_value_id": "text",
"external_id": "text",
"name": "text",
"sku_ids": [
1
],
"display_order": 1
}
],
"display_order": 1
}
],
"skus": [
{
"id": 1,
"offer_id": 1,
"merchant_id": 1,
"external_id": "text",
"name": "text",
"asin": "text",
"gtin": "text",
"upc": "text",
"ean": "text",
"isbn": "text",
"in_stock": true,
"qty_available": 1,
"inventory_tracked": true,
"sale_price": 1,
"retail_price": 1,
"currency": "text",
"external_currency": "text",
"presented_currency": "text",
"taxable": true,
"tax_type": "DEFAULT",
"albums": [
{
"id": 1,
"parent_id": 1,
"type": "OFFER",
"name": "text",
"media": [
{
"id": 1,
"album_id": 1,
"external_id": "text",
"cloud_id": "text",
"url": "text",
"source_url": "text",
"type": "IMAGE",
"display_order": 1,
"alt_text": "text",
"primary": true
}
],
"primary_media": {
"id": 1,
"album_id": 1,
"external_id": "text",
"cloud_id": "text",
"url": "text",
"source_url": "text",
"type": "IMAGE",
"display_order": 1,
"alt_text": "text",
"primary": true
}
}
],
"variant_values": [
{
"variant": "text",
"value": "text"
}
],
"type": "PHYSICAL",
"status": "UNAVAILABLE",
"date_created": "2025-07-10T06:35:24.346Z",
"date_last_modified": "2025-07-10T06:35:24.346Z",
"sku_dimensions": {
"sku_id": 1,
"weight": 1,
"height": 1,
"width": 1,
"length": 1,
"type": "SKU"
},
"shipping_dimensions": {
"sku_id": 1,
"weight": 1,
"height": 1,
"width": 1,
"length": 1,
"type": "SKU"
},
"metadata": [
{
"version": 1,
"type": "STRING",
"external_type": "text",
"key": "text",
"value": {},
"external_id": "text",
"source": "INTERNAL"
}
],
"display_order": 1
}
],
"albums": [
{
"id": 1,
"parent_id": 1,
"type": "OFFER",
"name": "text",
"media": [
{
"id": 1,
"album_id": 1,
"external_id": "text",
"cloud_id": "text",
"url": "text",
"source_url": "text",
"type": "IMAGE",
"display_order": 1,
"alt_text": "text",
"primary": true
}
],
"primary_media": {
"id": 1,
"album_id": 1,
"external_id": "text",
"cloud_id": "text",
"url": "text",
"source_url": "text",
"type": "IMAGE",
"display_order": 1,
"alt_text": "text",
"primary": true
}
}
],
"type": "PHYSICAL",
"status": "UNAVAILABLE",
"publishing_status": "NOT_PUBLISHED",
"date_created": "2025-07-10T06:35:24.346Z",
"date_last_modified": "2025-07-10T06:35:24.346Z",
"date_last_consolidated": "2025-07-10T06:35:24.346Z",
"three_d_enabled": false,
"three_d_resource": "text",
"commission_rate": 1,
"currency_symbol": "text",
"presented_currency": "text",
"default_image_url": "text",
"subscription_status": "NOT_SUBSCRIBED",
"external_data": {},
"collections": [
{
"id": 1,
"external_id": "text",
"merchant_id": 1,
"parent_id": 1,
"name": "text",
"handle": "text",
"description": "text",
"status": "INACTIVE",
"type": "CUSTOM",
"media": {
"source_url": "text",
"alt": "text",
"height": 1,
"width": 1,
"date_created": "2025-07-10T06:35:24.346Z"
},
"date_created": "2025-07-10T06:35:24.346Z",
"date_last_modified": "2025-07-10T06:35:24.346Z"
}
],
"shipping": {
"message": "text",
"methods": [
{
"external_id": "text",
"name": "text",
"price": {
"amount": 1,
"currency": "USD"
},
"regions": {
"countries": [
"US"
]
},
"conditions": [
{
"price": {
"amount": 1,
"currency": "USD"
},
"weight": {
"value": 1,
"unit": "INCHES"
},
"type": "TOTAL_PRICE",
"operator": "LESS_THAN_OR_EQUAL_TO"
}
]
}
]
},
"tags": [
"text"
]
}
],
"last": true,
"total_pages": 1,
"total_elements": 1,
"first": true,
"number_of_elements": 1,
"size": 1,
"number": 1,
"empty": true,
"next_page_cursor": "text",
"pageable": {
"page_number": 1,
"page_size": 1,
"sort": {
"unsorted": true,
"sorted": true,
"empty": true
},
"offset": 1,
"paged": true,
"unpaged": true
},
"sort": {
"unsorted": true,
"sorted": true,
"empty": true
}
}Last updated
Was this helpful?