Parameter Types

The parameter types that are available for use with endpoints.

URL Encoding

All parameter values must be URL encoded. Failure to do so may result in unexpected results from the API. Refer to the documentation of the programming language you are using for more information on URL encoding.

// This is NOT URL Encoded
&filterMerchant=Starwood Hotels & Resorts|Wyndham Hotel Group

// This is URL Encoded correctly
&filterMerchant=Starwood%20Hotels%20%26%20Resorts%7CWyndham%20Hotel%20Group

Filters

Filters allow you to filter our data by ways you choose. Refer to the Request Parameters table of each endpoint for available filters.

Parameter Format Description Example
filter{FieldName}=value Just listing one value will filter the results by that value. filterBrand=Nike - Filter by the brand Nike.
filter{FieldName}=value* Add an ending asterisk to match additional words after the value. filterBrand=Nike* - Filter by brands that start with Nike, eg. Nike, Nike Kids, Nike Golf, etc.
filter{FieldName}=*value Add a starting asterisk to match additional words before the value. filterCategory=*shoes - Filter by the categories that end with shoes, eg. shoes, womens shoes, mens shoes, etc.
filter{FieldName}=*value* Add a starting and ending asterisk to match additional words on both sides of the value. filterMerchant=*Shoes* - Filter by the merchants that have Shoes in their name, eg. Butter Shoes, Shoes for Crews, etc.
filter{FieldName}=value1*value2 Add an asterisk between words to match additional words between the values. filterKeyword=Ralph*Jeans - Filter by Keywords that start with ralph, end with jeans, and have words in between, eg. Ralph Lauren Jeans.
filter{FieldName}=*value1*value2* Add a starting, ending and between asterisk to match additional words on both sides of and between the values. filterKeywords=*Larkee*Leg* - Filter by Keywords that have Larkee Leg in them, eg. Diesel Larkee Skinny Leg Jeans.
filter{FieldName}=!value Using an exclamation point will remove exact matches of the word from results. filterBrand=Nike - Will not return Nike but will return other Nike brands.
filter{FieldName}=!*value Using an exclamation point with a starting asterisk will remove additonal words before the value. filterMerchant=!*Shoes - Will remove merchants like Infinity Shoes, Nina Shoes, etc.
filter{FieldName}=!value* Using an exclamation point with an ending asterisk will remove additonal words after the value. filterMerchant=!Shoes* - Will remove merchants like Shoes for Crews, Shoes and Style, etc.
filter{FieldName}=!*value* Using an exclamation point with starting and ending asterisks will remove additional words on both sides of the value. filterBrand=!*Nike* - Will not return any Nike brands.
filter{FieldName}=value1|value2|etc. Using pipe seperated values will filter the results by multiple values. filterMerchant=Zappos.com|6pm.com|Shoebuy.com - Filter by the merchants Zappos.com, 6pm.com and Shoebuy.com
filter{FieldName}=!*value1|value2*|etc. Using pipe seperated values with asterisks and exclamation points will filter the results by multiple values with looser matches or removing certain matches. filterKeyword=Nike*|!*Nike Sandals - Filters by keyword Nike while not returning Nike Sandals.

Null Values

Some filters allow null to be passed in as a value. Refer to the Request Parameters table of each endpoint to see which filters allow null values.

Parameter Format Description Example
filter{FieldName}=null Using null will return results where the field does not contain a value. filterCity=null - Filter results where city is not specified.
filter{FieldName}=!null Using an exclamation point in front of null will return results where the field contains some value. filterCouponCode=!null - Filter results where couponCode is specified.

Ranges

Ranges are specialized filters for numeric values and dates. They allow you to filter results by simulating equal to (=), less than or equal to (<=) and greater than or equal to (>=). Dates must be in YYYYMMDD Parameter Format. Refer to the Request Parameters table of each endpoint for available filters that use ranges.

Parameter Format Description Example
filter{FieldName}=value Just using the value will return results equal to the value. filterPrice=17.50 - Returns products that have a price equal to $17.50
filter{FieldName}=value1, Placing a comma before a number will return anything greater than or equal to value1. filterPrice=15.00, - Returns any products with a price greater than or equal to $15.00
filter{FieldName}=,value2 Placing a comma then a number will return anything less than or equal to value2. filterPrice=,120.00 - Returns any products with a price less than or equal to $120.00
filter{FieldName}=value1,value2 Returns results that are greater than or equal to value1 and less than or equal to value2. commissionDateRange=20140124,20140128 - Returns any commissions with a date greater than or equal to 2014-01-24 and less than or equal to 2014-01-28.

Sort By

Sort the data in either asc (ascending) or desc (descending) order. Refer to the Request Parameters table of each endpoint for available fields that allow sorting.

Parameter Format Description Example
sortBy=value Will sort by the value by the default - ascending order. sortBy=price - Sorts the price in ascending order (0-9).
sortBy=value asc or desc Will sort by the value in either ascending or descrnding order. sortBy=merchant+asc - Sorts the merchants in ascending order (0-9A-Z).
sortBy=value1 asc or desc| value2 asc or desc|etc. Using a pipe seperated list of values will create a sort within a sort. sortBy=numProducts+desc|merchant+asc - Sorts by numProducts in descending order. If any results have the same number of products, a sort is then done on the merchant names in acending order.

Group By

Group the results by a common value. Refer to the Request Parameters table of each endpoint for available fields that allow grouping.

Parameter Format Description Example
groupBy=value Groups the results by the value given. Grouping offers some extra fields for some endpoints. groupBy=merchant - Groups the results by merchant name.