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

Search Offers

Searches the merchant's products with the filters in a JSON body.

Relay - Search Offers

post

Searches the merchant's products with the filters in a JSON body. It returns the same results as Get Offers with the same values as query parameters, so the platform support, pagination and filter notes there apply here too. ids is not supported yet.

Path parameters
merchant_idinteger · int32Required

Violet ID of the merchant.

Example: 12345
Header parameters
X-Violet-TokenstringRequired

Violet auth token. It must belong to the developer that owns the app in X-Violet-App-Id.

X-Violet-App-SecretstringRequired

Secret of the app in X-Violet-App-Id.

X-Violet-App-Idinteger · int32Required

ID of the Violet app making the request. The app must be connected to the merchant.

Example: 20001
Body

Filters for searching a merchant's products on their ecom platform. Every field is optional. Each filter has the same meaning and platform support as the query parameter of the same name on Get Offers.

querystringOptional

Not supported. A non-blank value is rejected with 400 operation_not_supported_exception.

statusstringOptional

Accepted but not applied by any platform.

idsstring[]Optional

Not supported yet. A non-empty value is rejected with 400 operation_not_supported_exception.

sortstringOptional

Accepted but not applied by any platform. Results come back in the platform's default order.

includestring[]Optional

Extras to include. Supported values are categories and metadata. Either one can require extra calls to the merchant's platform. Applied by Shopify only; other platforms ignore it. Any other value is rejected with 400 invalid_parameter, on every platform.

pageinteger · int32Optional

Page number, starting at 1. Used by page-number platforms (for example WooCommerce and BigCommerce). Cursor platforms such as Shopify ignore it and use next_page_cursor. Defaults to 1.

Example: 1
sizeinteger · int32Optional

Number of results per page. Values below 1 are treated as 1. Violet reduces larger values only where noted below. Elsewhere the value is sent on as given and the platform may apply its own limit. Caps: Shopify and BigCommerce 250, WooCommerce 100. Defaults to 20.

Example: 50
category_idstringOptional

Only return products in this category or collection. Applied by WooCommerce and BigCommerce (a category ID) and by Shopify (a numeric collection ID, any other value is ignored). Shopify applies it only for merchants on a custom app connection, and ignores it on other connections.

Example: 428123456789
sort_orderstringOptional

Accepted but not applied by any platform. Results come back in the platform's default order.

updated_afterstringOptional

Only return products updated after this time. ISO 8601 timestamp, for example 2026-01-15T00:00:00Z. A date without a time is rejected with 400 invalid_parameter. Applied by WooCommerce, BigCommerce and Shopify. Shopify applies it only for merchants on a custom app connection, and ignores it on other connections.

updated_beforestringOptional

Only return products updated before this time. ISO 8601 timestamp, for example 2026-01-15T00:00:00Z. A date without a time is rejected with 400 invalid_parameter. Applied by BigCommerce and Shopify. Shopify applies it only for merchants on a custom app connection, and ignores it on other connections.

created_afterstringOptional

Accepted but not applied by any platform.

created_beforestringOptional

Accepted but not applied by any platform.

next_page_cursorstringOptional

Cursor for the next page, copied from next_page_cursor in the previous response. Used by cursor platforms such as Shopify. Filters sent with a cursor are ignored, because the cursor carries the filters of the first request.

Responses
200

A page of offers.

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/relay/merchants/{merchant_id}/offers/search
POST /v1/relay/merchants/{merchant_id}/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: 115

{
  "category_id": "428123456789",
  "updated_after": "2026-03-01T00:00:00Z",
  "include": [
    "categories",
    "metadata"
  ],
  "size": 50
}
{
  "content": [
    {
      "external_id": "7469837175852",
      "name": "Canvas Weekender Bag",
      "description": "Durable cotton canvas weekender with leather handles.",
      "source": "SHOPIFY",
      "seller": "Example Goods",
      "vendor": "Example Goods",
      "merchant_id": 12345,
      "available": true,
      "visible": true,
      "min_price": 12900,
      "max_price": 12900,
      "currency": "USD",
      "type": "PHYSICAL",
      "status": "AVAILABLE",
      "publishing_status": "NOT_PUBLISHED",
      "external_url": "https://shop.example.com/products/canvas-weekender-bag",
      "variants": [
        {
          "name": "Color",
          "values": [
            {
              "name": "Natural"
            }
          ]
        }
      ],
      "skus": [
        {
          "external_id": "42001965334700",
          "name": "Canvas Weekender Bag - Natural",
          "in_stock": true,
          "qty_available": 14,
          "retail_price": 15900,
          "sale_price": 12900,
          "currency": "USD",
          "taxable": true,
          "type": "PHYSICAL",
          "variant_values": [
            {
              "variant": "Color",
              "value": "Natural"
            }
          ]
        }
      ],
      "albums": [
        {
          "type": "OFFER",
          "name": "Canvas Weekender Bag",
          "media": [
            {
              "external_id": "34567890123",
              "source_url": "https://cdn.example.com/files/weekender-natural.jpg",
              "type": "IMAGE",
              "display_order": 1,
              "primary": true
            }
          ]
        }
      ]
    }
  ],
  "last": false,
  "number_of_elements": 1,
  "empty": false,
  "next_page_cursor": "eyJsYXN0X2lkIjo3NDY5ODM3MTc1ODUyfQ"
}

Last updated

Was this helpful?