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:
Upcoming Enhancements
Accurately mapped subscription_status. This is a part of a new Violet feature. For now, you can ignore the value assigned here.
Filter by available offers
Merchant Ids to filter by
The parent/container product ID
Available options:
NOT_PUBLISHED,
PUBLISHED
Used with the beta flag. A NLP-based search query
Name of Merchant Selling Product
Property to sort by in camelCase
Offer category from ecom-platform
Available options:
UNAVAILABLE,
AVAILABLE,
DISABLED_UNAVAILABLE,
DISABLED_AVAILABLE,
FOR_DELETION,
ARCHIVED
Available options:
NOT_SUBSCRIBED,
SUBSCRIBED
Name of Original Vendor (Brand)
Response default - application/json
The actual content of the response; A list of the result objects
Grouped of media for the Offer. Note: For most commerce platforms there will only be a single album per Offer.
Available options:
OFFER,
SKU
content.albums.media. album_id
content.albums.media. alt_text
Text describing the media. This value is sourced from the merchant.
Maximum length: 512
content.albums.media. cloud_id
The unique ID of hosted cloud entity. Only present on media from self-hosted platforms.
content.albums.media. display_order
The order in which the merchant displayed the media in relation to other media in the same collection.
content.albums.media. external_id
The ID of the media in the merchants store.
content.albums.media. primary
If the media is the primary or default image in the merchants store for an Offer or Sku. This is typically the cover image on a product details page.
content.albums.media. source_url
The original URL from the merchants system.
content.albums.media. type
Available options:
IMAGE,
VIDEO
The URL that should be used when displaying media within your app. For cloud hosted commerce platforms that provide a CDN this will often be the same as the source_url property. For self-hosted platforms this will typically be a Violet CDN URL.
content.albums. primary_media
content.albums.primary_media. album_id
content.albums.primary_media. alt_text
Text describing the media. This value is sourced from the merchant.
Maximum length: 512
content.albums.primary_media. cloud_id
The unique ID of hosted cloud entity. Only present on media from self-hosted platforms.
content.albums.primary_media. display_order
The order in which the merchant displayed the media in relation to other media in the same collection.
content.albums.primary_media. external_id
The ID of the media in the merchants store.
content.albums.primary_media. id
content.albums.primary_media. primary
If the media is the primary or default image in the merchants store for an Offer or Sku. This is typically the cover image on a product details page.
content.albums.primary_media. source_url
The original URL from the merchants system.
content.albums.primary_media. type
Available options:
IMAGE,
VIDEO
content.albums.primary_media. url
The URL that should be used when displaying media within your app. For cloud hosted commerce platforms that provide a CDN this will often be the same as the source_url property. For self-hosted platforms this will typically be a Violet CDN URL.
Is the product available for purchase.
Collections this offer belongs to
content.collections. merchant_id
content.collections. date_created
Date of creation of this collection on platform
content.collections. date_last_modified
Date of last update of this collection on platform
content.collections. description
Description of this collection
content.collections. external_id
content.collections. handle
Handle of this collection
content.collections. media
content.collections.media. alt
content.collections.media. date_created
Date of media creation on platform
content.collections.media. height
content.collections.media. source_url
content.collections.media. width
content.collections. parent_id
Parent ID for platforms that have a parent-child collection structure.
content.collections. status
Status of this collection
Available options:
INACTIVE,
ACTIVE,
SYNC_IN_PROGRESS,
FOR_DELETION
Available options:
CUSTOM,
AUTOMATED
Base Currency of Offer. Intended for reference only. The currency property of the SKU is the currency source of truth.
Symbol representing the desired currency
Date of offer creation in ISO 8601 format.
content. date_last_consolidated
Date of last consolidation in ISO 8601 format. This date is jittered for performance reasons and can be in the future
content. date_last_modified
Date of last offer update in ISO 8601 format.
content. default_image_url
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.
Description of the offer. Note: this value may contain HTML elements.
Maximum length: 65000
The raw external product data from the external commerce platform
The ID of the product in the merchants external store.
The URL to the product page in the merchants store.
Maximum Price the Offer sells for.
Additional Meta Data of the Offer
content.metadata. external_id
ID of the meta object in the external commerce platform
content.metadata. external_type
Type of the value in the external commerce platform
The source the meta object originated from, either EXTERNAL or INTERNAL, with EXTERNAL representing data from the external commerce platform
Available options:
INTERNAL,
EXTERNAL
Available options:
STRING,
JSON,
INTEGER,
LONG,
DECIMAL,
BOOLEAN
The meta value. Values of type JSON will be stringified
Minimum Price the Offer sells for.
content. presented_currency
The presented currency of this SKU
The parent/container product ID. Note: this is a legacy property and is now considered deprecated.
content. publishing_status
Available options:
NOT_PUBLISHED,
PUBLISHED
Name of merchant selling product.
[ALPHA] - Shipping data for the Offer.
Context regarding the shipping data for this Offer.
List of available shipping methods for this Offer.
content.shipping.methods. conditions
Conditions that must be met for the method to be available.
content.shipping.methods.conditions. operator
Operator indicating if the price or weight is >= or <= the condition value.
Available options:
LESS_THAN_OR_EQUAL_TO,
GREATER_THAN_OR_EQUAL_TO
content.shipping.methods.conditions. price
Price in cents required to enable the shipping method.
content.shipping.methods.conditions. type
Condition type, whether it's price or weight based.
Available options:
TOTAL_PRICE,
TOTAL_WEIGHT
content.shipping.methods.conditions. weight
Weight required to enable the shipping method.
content.shipping.methods. external_id
ID of the shipping method in the external commerce system.
content.shipping.methods. name
Name of the shipping method as provided by the merchant.
content.shipping.methods. price
Price in cents required to enable the shipping method.
content.shipping.methods.price. amount
content.shipping.methods.price. currency
Available options:
USD,
AED,
AFN,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BWP,
BZD,
CAD,
CDF,
CHF,
CLP,
CNY,
COP,
CRC,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
ISK,
JMD,
JPY,
KES,
KGS,
KHR,
KMF,
KRW,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRO,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
STD,
SVC,
SZL,
THB,
TJS,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
UYU,
UZS,
VND,
VUV,
WST,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMW,
BTN
content.shipping.methods. regions
Regions this shipping method is enabled for.
content.shipping.methods.regions. countries
(enum<string> | null)[] | null
List of ISO 3166 Country Codes
Available options:
US,
AU,
AT,
BE,
CA,
DK,
FI,
FR,
DE,
HK,
IE,
IT,
JP,
LU,
MX,
NL,
NZ,
NO,
PT,
SG,
ES,
SE,
CH,
GB,
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AZ,
BS,
BH,
BD,
BB,
BY,
BZ,
BJ,
BM,
BT,
BO,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
KH,
CM,
CV,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CY,
CZ,
DJ,
DM,
DO,
EC,
EG,
SV,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
GF,
PF,
TF,
GA,
GM,
GE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HU,
IS,
IN,
ID,
IR,
IQ,
IM,
IL,
JM,
JE,
JO,
KZ,
KE,
KI,
KP,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
AN,
NC,
NI,
NE,
NG,
NU,
NF,
MP,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PR,
QA,
RE,
RO,
RU,
RW,
SH,
KN,
LC,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SK,
SI,
SB,
SO,
ZA,
GS,
LK,
SD,
SR,
SJ,
SZ,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW
Sku's are unique combinations of Variants the compose a purchasable entity. When placing orders a Sku is the item that will be purchased.
The base currency of this Sku.
ID of the Merchant that originated the Sku.
ID of the parent Offer that this Sku is a child of.
Sale Price of the Sku. This is the actual sale cost when the Sku is purchased.
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
content.skus.albums. parent_id
Available options:
OFFER,
SKU
content.skus.albums. media
content.skus.albums.media. album_id
content.skus.albums.media. alt_text
Text describing the media. This value is sourced from the merchant.
Maximum length: 512
content.skus.albums.media. cloud_id
The unique ID of hosted cloud entity. Only present on media from self-hosted platforms.
content.skus.albums.media. display_order
The order in which the merchant displayed the media in relation to other media in the same collection.
content.skus.albums.media. external_id
The ID of the media in the merchants store.
content.skus.albums.media. id
content.skus.albums.media. primary
If the media is the primary or default image in the merchants store for an Offer or Sku. This is typically the cover image on a product details page.
content.skus.albums.media. source_url
The original URL from the merchants system.
content.skus.albums.media. type
Available options:
IMAGE,
VIDEO
content.skus.albums.media. url
The URL that should be used when displaying media within your app. For cloud hosted commerce platforms that provide a CDN this will often be the same as the source_url property. For self-hosted platforms this will typically be a Violet CDN URL.
content.skus.albums. primary_media
content.skus.albums.primary_media. album_id
content.skus.albums.primary_media. alt_text
Text describing the media. This value is sourced from the merchant.
Maximum length: 512
content.skus.albums.primary_media. cloud_id
The unique ID of hosted cloud entity. Only present on media from self-hosted platforms.
content.skus.albums.primary_media. display_order
The order in which the merchant displayed the media in relation to other media in the same collection.
content.skus.albums.primary_media. external_id
The ID of the media in the merchants store.
content.skus.albums.primary_media. id
content.skus.albums.primary_media. primary
If the media is the primary or default image in the merchants store for an Offer or Sku. This is typically the cover image on a product details page.
content.skus.albums.primary_media. source_url
The original URL from the merchants system.
content.skus.albums.primary_media. type
Available options:
IMAGE,
VIDEO
content.skus.albums.primary_media. url
The URL that should be used when displaying media within your app. For cloud hosted commerce platforms that provide a CDN this will often be the same as the source_url property. For self-hosted platforms this will typically be a Violet CDN URL.
Amazon Standard Identification Number
content.skus. date_created
Date when the Sku was first created in Violet.
content.skus. date_last_modified
Date when the Sku was last updated in Violet.
content.skus. display_order
The order that the merchant has chosen to display this Sku in relation to other Sku's that are children of the same Offer.
The ID of the Sku in the merchants external store.
Is the Sku in stock in the merchants external store.
content.skus. inventory_tracked
Is the Sku's inventory tracked in the merchants system. Untracked inventory can be oversold even when the available quantity is 0.
International Standard Book Number
content.skus. presented_currency
The presented currency of this Sku.
content.skus. quantity_available
The total quantity of this Sku available for purchase.
content.skus. retail_price
Retail Price of the Sku. This is the recommended or common price of the Sku and is typically not what the customer will be charged..
content.skus. shipping_dimensions
Individual Sku Dimensions
content.skus.shipping_dimensions. height
content.skus.shipping_dimensions. length
content.skus.shipping_dimensions. sku_id
ID of SKU Dimensions Belong To
content.skus.shipping_dimensions. type
Available options:
SKU,
SHIPPING
content.skus.shipping_dimensions. weight
content.skus.shipping_dimensions. width
content.skus. sku_dimensions
Individual Sku Dimensions
content.skus.sku_dimensions. height
content.skus.sku_dimensions. length
content.skus.sku_dimensions. sku_id
ID of SKU Dimensions Belong To
content.skus.sku_dimensions. type
Available options:
SKU,
SHIPPING
content.skus.sku_dimensions. weight
content.skus.sku_dimensions. width
Available options:
UNAVAILABLE,
AVAILABLE,
DISABLED_UNAVAILABLE,
DISABLED_AVAILABLE,
FOR_DELETION,
ARCHIVED
Available options:
DEFAULT,
APPAREL,
SERVICE
content.skus. variant_values
Variant Values that apply to this SKU
content.skus.variant_values. value
content.skus.variant_values. variant
Commerce platform the offer was sourced from.
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. source_category_name
Original Category on Source Platform
Current status of the Offer.
Available options:
UNAVAILABLE,
AVAILABLE,
DISABLED_UNAVAILABLE,
DISABLED_AVAILABLE,
FOR_DELETION,
ARCHIVED
content. subscription_status
Available options:
NOT_SUBSCRIBED,
SUBSCRIBED
Is the product 3D Enabled
Type of product. Note: Offers with a type of BUNDLED cannot be purchased through the API at this time due to ecom platform limitations.
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
Product variations configured by the merchant in their external store. Note: Variations can have any name the merchant chooses to use. There is no pre-defined set of possible variants or variant values.
content.variants. display_order
The order the variants are displayed in.
content.variants. external_id
ID of the Variant on the External Ecommerce Platform
The name given to the Variant by the merchant.
content.variants. product_variant_id
ID of the Product Variant
content.variants.values. display_order
The order the variant values are displayed in.
content.variants.values. external_id
ID of the Variant in the External Ecommerce Platform
content.variants.values. id
content.variants.values. name
content.variants.values. product_variant_value_id
ID of the Product Variation Value
content.variants.values. sku_ids
ID's of SKU's containing this Variant Value
Is the variant a visual characteristic. Common examples of this would be Color, Pattern, or Material.
Name of source vendor or brand.
Is the product hidden in the merchants store. Note: a product can be hidden while still being available for purchase.
Boolean indicating if the response content is empty
Boolean indicating if this is the first page of the response
Boolean indicating if this is the last page
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.
The page number selected at request time
The total number of objects in this specific response
Violet wrapper for springframework pageable
The current page number (one based)
The number of elements per page
Boolean indicating if the result is paged
Violet Wrapper for springframework sort
Boolean indicating if the result set is empty
Boolean indicating if the result set is sorted
Boolean indicating if the result set is unsorted
Boolean indicating if the result is unpaged
The page size selected at request time
Violet Wrapper for springframework sort
Boolean indicating if the result set is empty
Boolean indicating if the result set is sorted
Boolean indicating if the result set is unsorted
The total count of objects available
The total count of pages available
