Search Offers

POST /catalog/offers/search returns eventually consistent data and is not real-time consistent. Use Offer Search for discovery, then use non-search Offer endpoints (for example, GET /catalog/offers/{offer_id}) when you need real-time Offer data.

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)

Filtering by Visibility

By default, this endpoint applies no visibility filter and returns all offers. Use the visible field in the request body to control this:

visible value	Result
omitted	All offers returned (no filter)
true	Only offers with visible=true
false	Only offers with visible=false (hidden offers)

When Offers Have visible=false

Offers are marked as hidden (visible=false) in the following cases:

• Stores without a public storefront - When a Shopify store has no public online store URL configured (common for test stores, development environments, or private stores)

• Unpublished products - Products that exist in Shopify but haven't been published to the online storefront (no publishedAt date)

Why this matters: During offer ingestion, Violet checks whether the merchant's store has a public online store URL. If it doesn't (which is typical for test stores), all offers are marked as visible=false by default, since there's no public storefront for customers to view them.

Visibility is determined during offer ingestion based on:

• Whether the merchant has a public online store URL configured in Shopify

• Whether the product is published in Shopify (publishedAt date)

Troubleshooting Empty Results

If you're not seeing any results from the search endpoint, check if the merchant's storefront is public and has products published. You can verify by omitting visible from the request body entirely — if results appear, their offers exist but have visible=false.

Search Offers

post

Maximum size limit of 100 results.

Query parameters

pageinteger · int32OptionalDefault: 1

sizeinteger · int32OptionalDefault: 20

exclude_publicbooleanOptionalDeprecatedDefault: true

exclude_hiddenbooleanOptionalDeprecated

Deprecated. Use the visible field in the request body instead.

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

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-06-10T00:02:53.839Z",
  "date_last_modified:max": "2026-06-10T00:02:53.839Z"
}

default

default response

{
  "content": [
    {
      "id": 1,
      "external_id": "text",
      "external_url": "text",
      "name": "Blue Running Sneakers",
      "description": "text",
      "source": "OTHER",
      "seller": "Foot Locker",
      "vendor": "Nike",
      "merchant_id": 1,
      "available": true,
      "visible": true,
      "min_price": 2999,
      "max_price": 5999,
      "currency": "USD",
      "external_currency": "USD",
      "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": 2999,
          "retail_price": 3999,
          "currency": "USD",
          "external_currency": "USD",
          "presented_currency": "USD",
          "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-06-10T00:02:53.839Z",
          "date_last_modified": "2026-06-10T00:02:53.839Z",
          "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-06-10T00:02:53.839Z",
      "date_last_modified": "2026-06-10T00:02:53.839Z",
      "date_last_consolidated": "2026-06-10T00:02:53.839Z",
      "three_d_enabled": false,
      "three_d_resource": "text",
      "commission_rate": 0.15,
      "currency_symbol": "text",
      "presented_currency": "USD",
      "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-06-10T00:02:53.839Z"
          },
          "date_created": "2026-06-10T00:02:53.839Z",
          "date_last_modified": "2026-06-10T00:02:53.839Z"
        }
      ],
      "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
  }
}