POST
/
catalog
/
offers
/
search
curl --request POST \
  --url https://sandbox-api.violet.io/v1/catalog/offers/search \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "visible": true,
  "available": true,
  "id": 123,
  "merchant_id": 123,
  "seller": "<string>",
  "vendor": "<string>",
  "product_id": "<string>",
  "external_id": "<string>",
  "name": "<string>",
  "publishing_status": "NOT_PUBLISHED",
  "subscription_status": "NOT_SUBSCRIBED",
  "status": "UNAVAILABLE",
  "source_category_name": "<string>",
  "tags": [
    "<string>"
  ],
  "merchant_ids": [
    123
  ],
  "min_price": 123,
  "max_price": 123,
  "sort_by": "<string>",
  "sort_direction": "<string>"
}'
{
  "content": [
    {
      "id": 123,
      "product_id": "<string>",
      "external_id": "<string>",
      "external_url": "<string>",
      "name": "<string>",
      "description": "<string>",
      "source": "OTHER",
      "seller": "Foot Locker",
      "vendor": "Nike",
      "merchant_id": 123,
      "available": true,
      "visible": true,
      "min_price": 123,
      "max_price": 123,
      "currency": "<string>",
      "external_currency": "<string>",
      "source_category_name": "<string>",
      "metadata": [
        {
          "version": 123,
          "type": "STRING",
          "external_type": "<string>",
          "key": "<string>",
          "value": {},
          "external_id": "<string>",
          "source": "INTERNAL"
        }
      ],
      "variants": [
        {
          "id": 123,
          "product_variant_id": "<string>",
          "external_id": "<string>",
          "name": "<string>",
          "visual": true,
          "values": [
            {
              "id": 123,
              "product_variant_value_id": "<string>",
              "external_id": "<string>",
              "name": "<string>",
              "sku_ids": [
                123
              ],
              "display_order": 123
            }
          ],
          "display_order": 123
        }
      ],
      "skus": [
        {
          "id": 123,
          "offer_id": 123,
          "merchant_id": 123,
          "external_id": "<string>",
          "name": "<string>",
          "asin": "<string>",
          "gtin": "<string>",
          "upc": "<string>",
          "ean": "<string>",
          "isbn": "<string>",
          "in_stock": true,
          "qty_available": 123,
          "inventory_tracked": true,
          "sale_price": 123,
          "retail_price": 123,
          "currency": "<string>",
          "external_currency": "<string>",
          "presented_currency": "<string>",
          "taxable": true,
          "tax_type": "DEFAULT",
          "albums": [
            {
              "id": 123,
              "parent_id": 123,
              "type": "OFFER",
              "name": "<string>",
              "media": [
                {
                  "id": 123,
                  "album_id": 123,
                  "external_id": "<string>",
                  "cloud_id": "<string>",
                  "url": "<string>",
                  "source_url": "<string>",
                  "type": "IMAGE",
                  "display_order": 123,
                  "alt_text": "<string>",
                  "primary": true
                }
              ],
              "primary_media": {
                "id": 123,
                "album_id": 123,
                "external_id": "<string>",
                "cloud_id": "<string>",
                "url": "<string>",
                "source_url": "<string>",
                "type": "IMAGE",
                "display_order": 123,
                "alt_text": "<string>",
                "primary": true
              }
            }
          ],
          "variant_values": [
            {
              "variant": "<string>",
              "value": "<string>"
            }
          ],
          "type": "PHYSICAL",
          "status": "UNAVAILABLE",
          "date_created": "2023-11-07T05:31:56Z",
          "date_last_modified": "2023-11-07T05:31:56Z",
          "sku_dimensions": {
            "sku_id": 123,
            "weight": 123,
            "height": 123,
            "width": 123,
            "length": 123,
            "type": "SKU"
          },
          "shipping_dimensions": {
            "sku_id": 123,
            "weight": 123,
            "height": 123,
            "width": 123,
            "length": 123,
            "type": "SKU"
          },
          "metadata": [
            {
              "version": 123,
              "type": "STRING",
              "external_type": "<string>",
              "key": "<string>",
              "value": {},
              "external_id": "<string>",
              "source": "INTERNAL"
            }
          ],
          "display_order": 123
        }
      ],
      "albums": [
        {
          "id": 123,
          "parent_id": 123,
          "type": "OFFER",
          "name": "<string>",
          "media": [
            {
              "id": 123,
              "album_id": 123,
              "external_id": "<string>",
              "cloud_id": "<string>",
              "url": "<string>",
              "source_url": "<string>",
              "type": "IMAGE",
              "display_order": 123,
              "alt_text": "<string>",
              "primary": true
            }
          ],
          "primary_media": {
            "id": 123,
            "album_id": 123,
            "external_id": "<string>",
            "cloud_id": "<string>",
            "url": "<string>",
            "source_url": "<string>",
            "type": "IMAGE",
            "display_order": 123,
            "alt_text": "<string>",
            "primary": true
          }
        }
      ],
      "type": "PHYSICAL",
      "status": "UNAVAILABLE",
      "publishing_status": "NOT_PUBLISHED",
      "date_created": "2023-11-07T05:31:56Z",
      "date_last_modified": "2023-11-07T05:31:56Z",
      "date_last_consolidated": "2023-11-07T05:31:56Z",
      "three_d_enabled": false,
      "three_d_resource": "<string>",
      "commission_rate": 123,
      "currency_symbol": "<string>",
      "presented_currency": "<string>",
      "default_image_url": "<string>",
      "subscription_status": "NOT_SUBSCRIBED",
      "external_data": {},
      "collections": [
        {
          "id": 123,
          "external_id": "<string>",
          "merchant_id": 123,
          "parent_id": 123,
          "name": "<string>",
          "handle": "<string>",
          "description": "<string>",
          "status": "INACTIVE",
          "type": "CUSTOM",
          "media": {
            "source_url": "<string>",
            "alt": "<string>",
            "height": 123,
            "width": 123,
            "date_created": "2023-11-07T05:31:56Z"
          },
          "date_created": "2023-11-07T05:31:56Z",
          "date_last_modified": "2023-11-07T05:31:56Z"
        }
      ],
      "shipping": {
        "message": "<string>",
        "methods": [
          {
            "external_id": "<string>",
            "name": "<string>",
            "price": {
              "amount": 123,
              "currency": "USD"
            },
            "regions": {
              "countries": [
                "US"
              ]
            },
            "conditions": [
              {
                "price": {
                  "amount": 123,
                  "currency": "USD"
                },
                "weight": {
                  "value": 123,
                  "unit": "INCHES"
                },
                "type": "TOTAL_PRICE",
                "operator": "LESS_THAN_OR_EQUAL_TO"
              }
            ]
          }
        ]
      },
      "tags": [
        "<string>"
      ]
    }
  ],
  "last": true,
  "total_pages": 123,
  "total_elements": 123,
  "first": true,
  "number_of_elements": 123,
  "size": 123,
  "number": 123,
  "empty": true,
  "next_page_cursor": "<string>",
  "pageable": {
    "page_number": 123,
    "page_size": 123,
    "sort": {
      "unsorted": true,
      "sorted": true,
      "empty": true
    },
    "offset": 123,
    "paged": true,
    "unpaged": true
  },
  "sort": {
    "unsorted": true,
    "sorted": true,
    "empty": true
  }
}

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.

Headers

​
X-Violet-Token
string
​
X-Violet-App-Secret
string
​
X-Violet-App-Id
integer

Query Parameters

​
page
integer
default:1
​
size
integer
default:20
​
exclude_public
boolean
default:true
​
exclude_hidden
boolean
default:true
​
extended
boolean
default:false
​
beta
boolean
default:false

Body

application/json

Offer Search Request

Response

default - application/json
default response

The response is of type object.