Search Offers

Enhanced Search (Beta)

An optional enhanced search mode is available for faster response times and more accurate queries. To use it, pass beta=true as a query parameter in your request. This is optional — the endpoint works fully without it.

What enhanced search adds:

• Faster response times

• NLP-based search queries

• Enhanced filter criteria

Current limitations of enhanced search:

• Returns partial offer data by default (passing extended=true will return full data but reduces performance)

• The following search body attributes are not yet supported in enhanced mode:

  • sort_by

  • sort_direction

Coming soon to enhanced search:

• Accurately mapped subscription_status (part of a new Violet feature — for now, you can ignore this value)

Search Offers

post

Maximum size limit of 100 results.

Query parameters

pageinteger · int32OptionalDefault: 1

sizeinteger · int32OptionalDefault: 20

exclude_publicbooleanOptionalDeprecatedDefault: true

exclude_hiddenbooleanOptionalDeprecatedDefault: true

extendedbooleanOptionalDefault: false

betabooleanOptionalDefault: false

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Body

application/json

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

Publishing status

Possible values:

subscription_statusstring · enumOptional

Subscription status

Possible values:

statusstring · enumOptional

Offer status

Possible values:

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

date_last_modified:minstring · date-timeOptional

Only include offers modified after this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_last_modified:maxstring · date-timeOptional

Only include offers modified before this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

Responses

default

default response

application/json

lastbooleanOptional

Boolean indicating if this is the last page

total_pagesinteger · int32Optional

The total count of pages available

total_elementsinteger · int32Optional

The total count of objects available

firstbooleanOptional

Boolean indicating if this is the first page of the response

number_of_elementsinteger · int32Optional

The total number of objects in this specific response

sizeinteger · int32Optional

The page size selected at request time

numberinteger · int32Optional

The page number selected at request time

emptybooleanOptional

Boolean indicating if the response content is empty

next_page_cursorstringOptional

Contains the cursor for the next page. This property will only be used for situations where the API does not support the page number/page size paradigm and it will mutually exclusive with the size/number fields in the response. If this property is returned it must be passed when requesting the next page from the API. Does not apply to endpoints that do not have a next_page_cursor query param documented.

post

/catalog/offers/search

HTTPcURLJavaScriptPython

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

{
  "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",
  "date_last_modified:min": "2026-04-03T13:59:42.352Z",
  "date_last_modified:max": "2026-04-03T13:59:42.352Z"
}

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": "2026-04-03T13:59:42.352Z",
          "date_last_modified": "2026-04-03T13:59:42.352Z",
          "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"
          },
          "trade_compliance": {
            "harmonized_system_code": "6109.10.00",
            "country_code_of_origin": "US",
            "province_code_of_origin": "CA"
          },
          "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": "2026-04-03T13:59:42.352Z",
      "date_last_modified": "2026-04-03T13:59:42.352Z",
      "date_last_consolidated": "2026-04-03T13:59:42.352Z",
      "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": "2026-04-03T13:59:42.352Z"
          },
          "date_created": "2026-04-03T13:59:42.352Z",
          "date_last_modified": "2026-04-03T13:59:42.352Z"
        }
      ],
      "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
  }
}