Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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
200

successful operation

application/json
lastbooleanOptional

Boolean indicating if this is the last page

total_pagesinteger · int32Optional

The total count of pages available

total_elementsinteger · int32Optional

The total count of objects available

firstbooleanOptional

Boolean indicating if this is the first page of the response

number_of_elementsinteger · int32Optional

The total number of objects in this specific response

sizeinteger · int32Optional

The page size selected at request time

numberinteger · int32Optional

The page number selected at request time

emptybooleanOptional

Boolean indicating if the response content is empty

next_page_cursorstringOptional

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.

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: 180

{
  "merchant_ids": [
    4821,
    4830,
    5012
  ],
  "tags": [
    "running",
    "trail"
  ],
  "min_price": 5000,
  "max_price": 15000,
  "available": true,
  "visible": true,
  "sort_by": "dateLastModified",
  "sort_direction": "desc"
}
{
  "content": [
    {
      "id": 248519,
      "external_id": "8429610926344",
      "external_url": "https://foot-locker.myshopify.com/products/air-flex-runner",
      "name": "Air Flex Runner",
      "description": "Lightweight everyday running shoe with a cushioned midsole and breathable knit upper.",
      "source": "SHOPIFY",
      "seller": "Foot Locker",
      "vendor": "Nike",
      "merchant_id": 4821,
      "available": true,
      "visible": true,
      "min_price": 8999,
      "max_price": 8999,
      "currency": "USD",
      "source_category_name": "Footwear > Running",
      "variants": [
        {
          "id": 71204,
          "external_id": "9015874281472",
          "name": "Size",
          "visual": false,
          "values": [
            {
              "id": 530118,
              "external_id": "Medium",
              "name": "Medium",
              "sku_ids": [
                411203
              ],
              "display_order": 1
            },
            {
              "id": 530119,
              "external_id": "Large",
              "name": "Large",
              "sku_ids": [
                411204
              ],
              "display_order": 2
            }
          ],
          "display_order": 1
        }
      ],
      "skus": [
        {
          "id": 411203,
          "offer_id": 248519,
          "merchant_id": 4821,
          "external_id": "44218309214",
          "name": "Air Flex Runner - Medium",
          "in_stock": true,
          "qty_available": 42,
          "inventory_tracked": true,
          "sale_price": 8999,
          "retail_price": 9999,
          "currency": "USD",
          "taxable": true,
          "tax_type": "APPAREL",
          "albums": [],
          "variant_values": [
            {
              "id": 530118,
              "external_id": "Medium",
              "name": "Medium",
              "display_order": 1
            }
          ],
          "type": "PHYSICAL",
          "status": "AVAILABLE",
          "date_created": "2024-01-15T10:30:00+0000",
          "date_last_modified": "2024-06-22T14:37:46+0000"
        },
        {
          "id": 411204,
          "offer_id": 248519,
          "merchant_id": 4821,
          "external_id": "44218309215",
          "name": "Air Flex Runner - Large",
          "in_stock": true,
          "qty_available": 18,
          "inventory_tracked": true,
          "sale_price": 8999,
          "retail_price": 9999,
          "currency": "USD",
          "taxable": true,
          "tax_type": "APPAREL",
          "albums": [],
          "variant_values": [
            {
              "id": 530119,
              "external_id": "Large",
              "name": "Large",
              "display_order": 2
            }
          ],
          "type": "PHYSICAL",
          "status": "AVAILABLE",
          "date_created": "2024-01-15T10:30:00+0000",
          "date_last_modified": "2024-06-22T14:37:46+0000"
        }
      ],
      "albums": [
        {
          "id": 312044,
          "parent_id": 248519,
          "type": "OFFER",
          "name": "Primary Album",
          "media": [
            {
              "id": 891022,
              "album_id": 312044,
              "external_id": "30250544889992",
              "url": "https://cdn.shopify.com/s/files/1/0582/6022/6184/products/air-flex-runner.jpg",
              "source_url": "https://cdn.shopify.com/s/files/1/0582/6022/6184/products/air-flex-runner.jpg",
              "type": "IMAGE",
              "display_order": 1,
              "primary": true,
              "alt_text": "Air Flex Runner side view"
            }
          ],
          "primary_media": {
            "id": 891022,
            "album_id": 312044,
            "external_id": "30250544889992",
            "url": "https://cdn.shopify.com/s/files/1/0582/6022/6184/products/air-flex-runner.jpg",
            "source_url": "https://cdn.shopify.com/s/files/1/0582/6022/6184/products/air-flex-runner.jpg",
            "type": "IMAGE",
            "display_order": 1,
            "primary": true,
            "alt_text": "Air Flex Runner side view"
          }
        }
      ],
      "type": "PHYSICAL",
      "status": "AVAILABLE",
      "publishing_status": "PUBLISHED",
      "subscription_status": "NOT_SUBSCRIBED",
      "date_created": "2024-01-15T10:30:00+0000",
      "date_last_modified": "2024-06-22T14:37:46+0000",
      "date_last_consolidated": "2024-06-22T14:37:46+0000",
      "three_d_enabled": false
    }
  ],
  "last": false,
  "total_pages": 287,
  "total_elements": 287,
  "first": true,
  "number_of_elements": 1,
  "size": 1,
  "number": 1,
  "empty": false,
  "pageable": {
    "page_number": 1,
    "page_size": 1,
    "sort": {
      "unsorted": false,
      "sorted": true,
      "empty": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "sort": {
    "unsorted": false,
    "sorted": true,
    "empty": false
  }
}
PreviousGet Offer by ID
NextSKUs

Last updated

Was this helpful?