​
POST /catalog/offers/search

Returns a page of Offers that match a specified query.

​
Request Parameters

query

*Only available in beta

Query string that performs a fuzzy search against all items you have access to, given additional filter criteria.

Example: storm trooper

name

Search criteria that specifically searches against the names of an offer.

Example: Star Wars

available

Filter criteria that matches against whether or not an offer is available.

Example: true

merchant_ids

Filter criteria against a list of given merchant_ids. Input is a list of integers.

Example: [10010, 10098]

tags

Filter criteria against a list of given tags associated with offers. Input is a list of integers.

Note: Tags are controlled by e-com platforms.

Example: [”madebygenai”, “kids”]

visible

Filter criteria that matches against whether or not an offer is visible.

Example: false

seller

Filter criteria that matches against the seller of an offer.

Example= nordstrom

vendor

Filter criteria that matches against the vendor of an offer.

Example: nike

max_price

Range criteria that sets a maximum price in scents search results can have.

Example: 10000

min_price

Range criteria that sets a minimum price in cents search results can have.

Example: 1000

sort_by

Property to sort results by. Must be specified in Camel Case.

Example: maxPrice

sort_direction
Default: "DESC"

Direction of sorted results. Ascending (asc) or descending (desc).

Example: asc

subscription_status

Filter criteria that matches against whether or not an offer has been subscribed to by your app.

Example: SUBSCRIBED

publishing_status

Filter criteria that matches against whether or not a merchant has published an offer

Example:PUBLISHED

​
Query Parameters

page
Default: "1"

Page to search offers from. Used for pagination of data.

Example: 1

size
Default: "20"

Number of items to return on a single page

Example: 50

beta*
Default: "false"

Denotes whether or not to use “beta” mode for Offer Search. This allows for faster, optimized queries.

Note: beta requires query to be passed in as a part of the request body.

Example: true

extended
Default: "false"

Denotes whether or not to pull the full Offer data or an optimized subset.

Note: Increased latencies for this request and beta mode required.

Example: true

Sample Request

JSON
curl -X POST https://sandbox-api.violet.io/v1/catalog/offers/search?beta=true \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json" \
-d '{"query": "flower shirt"}'

Sample Response

JSON 
{
    "content": [
        {
            "id": 16908,
            "name": "Soy Candle",
            "description": "Inspired by gardens and the desert, Form candles are made with hand-poured soy wax. Clean burning and peaceful, once the candle is spent, the vessel becomes a planter!<br><ul><li>Once the candle has burned down, just flip the lid to the bottom to catch water, and add your favorite plant.</li></ul>",
            "seller": "Violet",
            "merchant_id": 10142,
            "available": true,
            "min_price": 3499,
            "max_price": 3499,
            "currency": "USD",
            "variants": [],
            "skus": [
                {
                    "id": 50039,
                    "offer_id": 16908,
                    "merchant_id": 10142,
                    "external_id": "62005056694338013db7e539",
                    "name": "Soy Candle",
                    "in_stock": true,
                    "inventory_tracked": true,
                    "taxable": true,
                    "tax_type": "DEFAULT",
                    "albums": [],
                    "variant_values": [],
                    "status": "AVAILABLE"
                }
            ],
            "albums": [],
            "three_denabled": false,
            "status": "AVAILABLE",
            "publishing_status": "PUBLISHED",
            "default_image_url": "https://cdn.schema.io/violet/62004fcd544098013eb779ae/8e8147108abcf19be300e8981cb960a8",
            "subscription_status": "NOT_SUBSCRIBED",
            "tags": [
                "candles"
            ]
        }
    ],
    "pageable": {
        "sort": {
            "unsorted": true,
            "sorted": false,
            "empty": true
        },
        "page_number": 0,
        "page_size": 20,
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "total_pages": 1,
    "total_elements": 1,
    "sort": {
        "unsorted": true,
        "sorted": false,
        "empty": true
    },
    "first": true,
    "number_of_elements": 3,
    "size": 20,
    "number": 0,
    "empty": false
}

✨ 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.
OverviewProduct Offers