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 ✨

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.

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-03-05T18:52:35.128Z",
  "date_last_modified:max": "2026-03-05T18:52:35.128Z"
}

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-03-05T18:52:35.128Z",
          "date_last_modified": "2026-03-05T18:52:35.128Z",
          "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-03-05T18:52:35.128Z",
      "date_last_modified": "2026-03-05T18:52:35.128Z",
      "date_last_consolidated": "2026-03-05T18:52:35.128Z",
      "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-03-05T18:52:35.128Z"
          },
          "date_created": "2026-03-05T18:52:35.128Z",
          "date_last_modified": "2026-03-05T18:52:35.128Z"
        }
      ],
      "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
  }
}