Search Offers
Searches the merchant's products with the filters in a JSON body.
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.
Violet ID of the merchant.
12345Violet auth token. It must belong to the developer that owns the app in X-Violet-App-Id.
Secret of the app in X-Violet-App-Id.
ID of the Violet app making the request. The app must be connected to the merchant.
20001Filters 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.
Not supported. A non-blank value is rejected with 400 operation_not_supported_exception.
Accepted but not applied by any platform.
Not supported yet. A non-empty value is rejected with 400 operation_not_supported_exception.
Accepted but not applied by any platform. Results come back in the platform's default order.
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.
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.
1Number 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.
50Only 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.
428123456789Accepted but not applied by any platform. Results come back in the platform's default order.
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.
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.
Accepted but not applied by any platform.
Accepted but not applied by any platform.
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.
A page of offers.
Boolean indicating if this is the last page
The total count of pages available
The total count of objects available
Boolean indicating if this is the first page of the response
The total number of objects in this specific response
The page size selected at request time
The page number selected at request time
Boolean indicating if the response content is empty
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.
A parameter is invalid (invalid_parameter), a filter that is not supported yet was used (operation_not_supported_exception), or the merchant's platform rejected Violet's stored connection (invalid_merchant_credentials, on platforms that detect it).
The app is not connected to the merchant (merchant_not_connected).
The token does not belong to the developer that owns the app, or the app is not subscribed to the Relay plan (insufficient_permissions).
The request failed in Violet or while reading from the merchant's platform.
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?