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": "<string>",
  "subscription_status": "<string>",
  "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": "<string>",
      "vendor": "<string>",
      "merchant_id": 123,
      "available": true,
      "visible": true,
      "min_price": 123,
      "max_price": 123,
      "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,
          "quantity_available": 123,
          "inventory_tracked": true,
          "sale_price": 123,
          "retail_price": 123,
          "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,
                  "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,
                "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"
          },
          "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,
              "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,
            "primary": true
          }
        }
      ],
      "three_d_enables": true,
      "three_d_resource": "<string>",
      "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",
      "commission_rate": 123,
      "weight_unit": "INCHES",
      "size_unit": "INCHES",
      "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,
          "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"
        }
      ],
      "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
query
string

Used with the beta flag. A NLP-based search query

visible
boolean

Filter by visible offers

available
boolean

Filter by available offers

id
integer
merchant_id
integer
seller
string

Name of Merchant Selling Product

vendor
string

Name of Original Vendor (Brand)

product_id
string

The parent/container product ID

external_id
string

External ID

name
string

Name of Product in Offer

publishing_status
string

Publishing status

subscription_status
string

Subscription status

source_category_name
string

Offer category from ecom-platform

tags
string[]

Tags to search for

merchant_ids
integer[]

Merchant Ids to filter by

min_price
integer

Minimum Price

max_price
integer

Maximum Price

sort_by
string

Property to sort by in camelCase

sort_direction
string

Direction to sort by

Response

default - application/json
content
object[]

The actual content of the response; A list of the result objects

last
boolean

Boolean indicating if this is the last page

total_pages
integer

The total count of pages available

total_elements
integer

The total count of objects available

first
boolean

Boolean indicating if this is the first page of the response

number_of_elements
integer

The total number of objects in this specific response

size
integer

The page size selected at request time

number
integer

The page number selected at request time

empty
boolean

Boolean indicating if the response content is empty

next_page_cursor
string

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.

pageable
object

Violet wrapper for springframework pageable

sort
object

Violet Wrapper for springframework sort