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.
Headers
X-Violet-Token
string
X-Violet-App-Secret
string
X-Violet-App-Id
integer
Query Parameters
page
integer
default: 1
size
integer
default: 20
exclude_public
boolean
default: true
exclude_hidden
boolean
default: true
extended
boolean
default: false
beta
boolean
default: false
Body
application/json
query
string
Used with the beta flag. A NLP-based search query
visible
boolean
Filter by visible offers
available
boolean
Filter by available offers
id
integer
merchant_id
integer
seller
string
Name of Merchant Selling Product
vendor
string
Name of Original Vendor (Brand)
product_id
string
The parent/container product ID
external_id
string
External ID
name
string
Name of Product in Offer
publishing_status
string
Publishing status
subscription_status
string
Subscription status
source_category_name
string
Offer category from ecom-platform
tags
string[]
Tags to search for
merchant_ids
integer[]
Merchant Ids to filter by
min_price
integer
Minimum Price
max_price
integer
Maximum Price
sort_by
string
Property to sort by in camelCase
sort_direction
string
Direction to sort by
Response
default - application/json
content
object[]
The actual content of the response; A list of the result objects
content.id
integer
content.product_id
string
required
The parent/container product ID
content.external_id
string
External ID
content.external_url
string
External URL
content.name
string
required
Name of Product in Offer
content.description
string
Product Description
content.source
enum<string>
required
Source Platform
Available options:
OTHER,
SHOPIFY,
MAGENTO,
MAGENTO_ONE,
WOOCOMMERCE,
BIGCOMMERCE,
LIGHTSPEED,
ECWID,
YAAS,
SPREECOMMERCE,
DEMANDWARE,
VOLUSION,
PRESTASHOP,
THREEDCART,
SYLIUS,
WIX,
SWELL,
MIVA,
WEBSPHERE,
ORACLECC,
SAPCC,
SQUARESPACE,
SHOPWARE,
COMMERCETOOLS,
MEDUSA,
ABICART,
SPRYKER,
MYSTORE,
CENTRA,
XCART,
VTEX,
KIBO,
SALEOR,
VENDO,
CHORD,
DIGITALRIVER,
SQUARE,
AMAZON,
BIGCARTEL,
CUSTOM
content.seller
string
Name of Merchant Selling Product
content.vendor
string
Name of Original Vendor
content.merchant_id
integer
required
Merchant ID
content.available
boolean
required
Is Product Available
content.visible
boolean
required
Is Product Visible
content.min_price
integer
required
Minimum Price the Product sells for
content.max_price
integer
Maximum Price the Product sells for
content.currency
string
Base Currency of Offer. Intended for reference only. The currency property of the SKU is the currency source of truth.
content.source_category_name
string
Original Category on Source Platform
content.metadata
object[]
Additional Meta Data of the Offer
content.metadata.version
number
Schema version
content.metadata.type
enum<string>
Type of the value
Available options:
STRING,
JSON,
INTEGER,
LONG,
DECIMAL,
BOOLEAN
content.metadata.external_type
string
Type of the value in the external commerce platform
content.metadata.key
string
The key of meta value
content.metadata.value
object
The meta value. Values of type JSON will be stringified
content.metadata.external_id
string
ID of the meta object in the external commerce platform
content.metadata.source
enum<string>
The source the meta object originated from, either EXTERNAL or INTERNAL, with EXTERNAL representing data from the external commerce platform
Available options:
INTERNAL,
EXTERNAL
content.variants
object[]
Product Variations
content.variants.id
integer
content.variants.product_variant_id
string
ID of the Product Variant
content.variants.external_id
string
ID of the Variant on the External Ecommerce Platform
content.variants.name
string
Variant Name
content.variants.visual
boolean
Is the variant visual
content.variants.values
object[]
Variant Values
content.variants.values.id
integer
content.variants.values.product_variant_value_id
string
ID of the Product Variation Value
content.variants.values.external_id
string
ID of the Variant in the External Ecommerce Platform
content.variants.values.name
string
Variant Value Name
content.variants.values.sku_ids
integer[]
ID's of SKU's containing this Variant Value
content.variants.values.display_order
integer
The order the variant values are displayed in.
content.variants.display_order
integer
The order the variants are displayed in.
content.skus
object[]
Product SKUs
content.skus.id
integer
content.skus.offer_id
integer
required
ID of the Offer
content.skus.merchant_id
integer
required
ID of the Merchant
content.skus.external_id
string
ID of the SKU on the External Ecom Platform
content.skus.name
string
Sku Name
content.skus.asin
string
Amazon Standard Identification Number
content.skus.gtin
string
Global Trade Item Number
content.skus.upc
string
Universal Product Code
content.skus.ean
string
European Article Number
content.skus.isbn
string
International Standard Book Number
content.skus.in_stock
boolean
Is the Product in Stock
content.skus.quantity_available
integer
Quantity Available
content.skus.inventory_tracked
boolean
Is the SKUs inventory tracked
content.skus.sale_price
integer
required
Sale Price of the SKU. This is the actual sale cost of the product is purchased.
content.skus.retail_price
integer
Retail Price of the SKU. This is the recommended or common price of the SKU.
content.skus.currency
string
required
The base currency of this SKU
content.skus.presented_currency
string
The presented currency of this SKU
content.skus.taxable
boolean
Is the product taxable
content.skus.tax_type
enum<string>
Type of Tax on this SKU
Available options:
DEFAULT,
APPAREL,
SERVICE
content.skus.albums
object[]
Sku Albums
content.skus.albums.id
integer
content.skus.albums.parent_id
integer
required
ID of the parent entity
content.skus.albums.type
enum<string>
required
Parent Type
Available options:
OFFER,
SKU
content.skus.albums.name
string
Name of Album
content.skus.albums.media
object[]
Album media
content.skus.albums.media.id
integer
content.skus.albums.media.album_id
integer
required
Album ID
content.skus.albums.media.external_id
string
External ID
content.skus.albums.media.cloud_id
string
ID of hosted cloud entity
content.skus.albums.media.url
string
Media URL
content.skus.albums.media.source_url
string
Media Source URL
content.skus.albums.media.type
enum<string>
Media Type
Available options:
IMAGE,
VIDEO
content.skus.albums.media.display_order
integer
Display Order
content.skus.albums.media.primary
boolean
Primary Media
content.skus.albums.primary_media
object
Product and SKU Media
content.skus.albums.primary_media.id
integer
content.skus.albums.primary_media.album_id
integer
required
Album ID
content.skus.albums.primary_media.external_id
string
External ID
content.skus.albums.primary_media.cloud_id
string
ID of hosted cloud entity
content.skus.albums.primary_media.url
string
Media URL
content.skus.albums.primary_media.source_url
string
Media Source URL
content.skus.albums.primary_media.type
enum<string>
Media Type
Available options:
IMAGE,
VIDEO
content.skus.albums.primary_media.display_order
integer
Display Order
content.skus.albums.primary_media.primary
boolean
Primary Media
content.skus.variant_values
object[]
Variant Values that apply to this SKU
content.skus.variant_values.variant
string
required
Variant Name
content.skus.variant_values.value
string
required
Variant Value
content.skus.type
enum<string>
required
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
content.skus.status
enum<string>
SKU Status
Available options:
UNAVAILABLE,
AVAILABLE,
DISABLED_UNAVAILABLE,
DISABLED_AVAILABLE,
FOR_DELETION,
ARCHIVED
content.skus.date_created
string
Date of SKU creation
content.skus.date_last_modified
string
Date of last SKU update
content.skus.sku_dimensions
object
Individual Sku Dimensions
content.skus.sku_dimensions.sku_id
integer
ID of SKU Dimensions Belong To
content.skus.sku_dimensions.weight
number
Weight of SKU
content.skus.sku_dimensions.height
number
Height of SKU
content.skus.sku_dimensions.width
number
Width of SKU
content.skus.sku_dimensions.length
number
Length of SKU
content.skus.sku_dimensions.type
enum<string>
Dimensions Type
Available options:
SKU,
SHIPPING
content.skus.shipping_dimensions
object
Individual Sku Dimensions
content.skus.shipping_dimensions.sku_id
integer
ID of SKU Dimensions Belong To
content.skus.shipping_dimensions.weight
number
Weight of SKU
content.skus.shipping_dimensions.height
number
Height of SKU
content.skus.shipping_dimensions.width
number
Width of SKU
content.skus.shipping_dimensions.length
number
Length of SKU
content.skus.shipping_dimensions.type
enum<string>
Dimensions Type
Available options:
SKU,
SHIPPING
content.skus.display_order
integer
Order to display SKU
content.albums
object[]
Product Albums
content.albums.id
integer
content.albums.parent_id
integer
required
ID of the parent entity
content.albums.type
enum<string>
required
Parent Type
Available options:
OFFER,
SKU
content.albums.name
string
Name of Album
content.albums.media
object[]
Album media
content.albums.media.id
integer
content.albums.media.album_id
integer
required
Album ID
content.albums.media.external_id
string
External ID
content.albums.media.cloud_id
string
ID of hosted cloud entity
content.albums.media.url
string
Media URL
content.albums.media.source_url
string
Media Source URL
content.albums.media.type
enum<string>
Media Type
Available options:
IMAGE,
VIDEO
content.albums.media.display_order
integer
Display Order
content.albums.media.primary
boolean
Primary Media
content.albums.primary_media
object
Product and SKU Media
content.albums.primary_media.id
integer
content.albums.primary_media.album_id
integer
required
Album ID
content.albums.primary_media.external_id
string
External ID
content.albums.primary_media.cloud_id
string
ID of hosted cloud entity
content.albums.primary_media.url
string
Media URL
content.albums.primary_media.source_url
string
Media Source URL
content.albums.primary_media.type
enum<string>
Media Type
Available options:
IMAGE,
VIDEO
content.albums.primary_media.display_order
integer
Display Order
content.albums.primary_media.primary
boolean
Primary Media
content.three_d_enabled
boolean
Is the product 3D Enabled
content.three_d_resource
string
3D Resource Object
content.type
enum<string>
Product Type
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED,
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
content.status
enum<string>
Status
Available options:
UNAVAILABLE,
AVAILABLE,
DISABLED_UNAVAILABLE,
DISABLED_AVAILABLE,
FOR_DELETION,
ARCHIVED
content.publishing_status
enum<string>
Publishing Status
Available options:
NOT_PUBLISHED,
PUBLISHED
content.date_created
string
Date of offer creation
content.date_last_modified
string
Date of last offer update
content.date_last_consolidated
string
Date of last consolidation. This date is jittered for performance reasons and can be in the future
content.commission_rate
number
Amount given by merchant
content.currency_symbol
string
Symbol representing the desired currency
content.presented_currency
string
The presented currency of this SKU
content.default_image_url
string
The default image for this Offer. Only present on responses from the Search API. In other cases this value will be on the album's primary media object.
content.subscription_status
enum<string>
Subscription status
Available options:
NOT_SUBSCRIBED,
SUBSCRIBED
content.external_data
object
The raw external product data from the external commerce platform
content.collections
object[]
Collections this offer belongs to
content.collections.id
integer
content.collections.external_id
string
External ID
content.collections.merchant_id
integer
required
Merchant ID
content.collections.parent_id
integer
Parent ID for platforms that have a parent-child collection structure.
content.collections.name
string
Name of this collection
content.collections.handle
string
Handle of this collection
content.collections.description
string
Description of this collection
content.collections.status
enum<string>
Status of this collection
Available options:
INACTIVE,
ACTIVE,
SYNC_IN_PROGRESS,
FOR_DELETION
content.collections.type
enum<string>
Type of this collection
Available options:
CUSTOM,
AUTOMATED
content.collections.media
object
Collection Media
content.collections.media.source_url
string
Source URL
content.collections.media.alt
string
Alt
content.collections.media.height
integer
Height
content.collections.media.width
integer
Width
content.collections.media.date_created
string
Date of media creation on platform
content.collections.date_created
string
Date of creation of this collection on platform
content.collections.date_last_modified
string
Date of last update of this collection on platform
content.tags
string[]
last
boolean
Boolean indicating if this is the last page
total_pages
integer
The total count of pages available
total_elements
integer
The total count of objects available
first
boolean
Boolean indicating if this is the first page of the response
number_of_elements
integer
The total number of objects in this specific response
size
integer
The page size selected at request time
number
integer
The page number selected at request time
empty
boolean
Boolean indicating if the response content is empty
next_page_cursor
string
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.