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

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
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": "2025-10-18T21:43:04.130Z",
  "date_last_modified:max": "2025-10-18T21:43:04.130Z"
}
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": "2025-10-18T21:43:04.130Z",
          "date_last_modified": "2025-10-18T21:43:04.130Z",
          "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"
          },
          "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": "2025-10-18T21:43:04.130Z",
      "date_last_modified": "2025-10-18T21:43:04.130Z",
      "date_last_consolidated": "2025-10-18T21:43:04.130Z",
      "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": "2025-10-18T21:43:04.130Z"
          },
          "date_created": "2025-10-18T21:43:04.130Z",
          "date_last_modified": "2025-10-18T21:43:04.130Z"
        }
      ],
      "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
  }
}
PreviousGet Offer by IDNextSKUs

Last updated

Was this helpful?