Search Phrase V4

Description

This service allows the users to search for a keyword and return product results matching that particular keyword.

Distinct features of V4 Products API

Syntax: https://api.macys.com/v4/catalog/search?searchphrase=search keywords

Examples:

- Keyword of brand ‘red dress’

https://api.macys.com/v4/catalog/search?searchphrase=keyword search

back to top

HTTP Method and Request URL

GET

https://api.macys.com/v4/catalog/search?searchphrase=keyword search 

back to top

Path and Query Parameters

HTTP Header Parameters

Parameter

Description

Mandatory

Sample Value

Accept

Specifies the output format. Can be application/json or application/xml.

Yes

application/json

application/xml

x-macys-webservice-client-id

Pass the apikey as a header value which is called x-macys-webservice-client-id. The api key is the 24 character alphanumeric string assigned to your application when you registered it. Click here for a list of your API keys.

Yes

xmj9js4jkdpe1983fmwu98gh

Query Parameters

Parameter

Description

Mandatory

Sample Value

searchphrase

whatever is entered in the search area

Yes

red dress

show

shows products or facets only.

If neither product or facet requested, shows BOTH products AND facets

No

product, facet
sortorderby default is the original order returned by the database call No

PRICE_ASCENDING

PRICE_DESCENDING

CUSTOMER_RATING

NEWNESS

BEST_SELLERS


perpage default 12. not more than 24 per page No 24
page What is current page number requested. default 1 No Optional 2
facetexpandall User wants to see ALL facet values listed for the search . Default will show only first 10 values for each facet No true
facet (Variable values) Will filter data pertinent to requested refinements. All 4 samples shown in column 1 can be requested separately or together No

CK, COLOR=[PINK,YELLOW]

PRICE=[‘*TO50]

PRICE=[0TO50]

PRICE=[50TO100]

Note: We do not allow whildcare "*" for upward PRICE queries. For example: PRICE=[50TO*]

CATEGORY=[women, apparel, shoes]

BRAND=COACH

DRESS_OCCASION=Casual

Note: facet values must be URL encoded.  For instance: Sales & Discounts would need to be formated: Sales%20%26%20Discounts

imagewidth imagewidth of images returned No
100 (Pixels)
upcimagewidth imagewidth of upc images returned No
100 (Pixels)
swatchimagewidth imagewidth of upc images returned No
100 (Pixels)
include This parameter allows you to return additional information about products such as promotions and product description. NOTE: Can only be used if the show=product also.
No promo,proddesc
avoidredirects When a search input includes the name of a Macy's category we return the category ID in the response as a redirect instead of the products and facets that would normally be delivered. (Ex. Search phrase: chanel)  You can avoid this by seeing this parameter to true. Default is false. No true or false
invassort Pass Inventory Assortment value to retreive Context specifc to return customized search results Default is SITE No STORE, SITE, JEWELRY, WEDDING_REGISTRY, SHOES, SEARCH_AND_SEND
appl Pass Application value to retreive Context specifc to return customized search results. Default is ASSOCIATE
No SITE, ASSOCIATE, MOBILE, MEW,SEO_LINK_MODULE, SEARCH_AND_SEND
device Pass Device value to retreive Context specifc to return customized search results. Default is TABLET No PHONE, TABLET, PC, POS
country Pass Country value to retreive Context specifc to return customized search results. Default is US
No US
callback If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.
No magicofmacysapi
zip Zip code of area you are trying to search for a product. Required if you do not specify locationNumber or city/state. No 94105
city You must specify state parameter if you specify the city parameter. No San Francisco
state You must specify city parameter if you specify the state parameter. No CA
latitude Search by global coordinates. You must specify longitude parameter if you specify the latitude parameter. (Required if also using longitude parameter) No 37.355965
longitude Search by global coordinates. You must specify latitude parameter if you specify the longitude parameter. No -122.01318

 

The Parameters are posted in URL. Multiple parameteres with values can be used in the same API call. However, multiple values for the same attribute should be specified by repeating the attribute name separated by ‘&’.

Facet Rules (include sort, page and ppp params in the facetMoreLessUrl links)

  1. If facet has less than 10 values, do not populate output schema attributes of facetMoreLess or facetMoreLessUrl.
  2. If facet has more than 10 values, and there is NO input parameter facetexpand, then the output schema will have for EACH FACET the attribute of facetMoreLess = “More” and facetMoreLessUrl would be a relative URL such as v4/catalog/search?searchphrase=red dress&sortorderby=DEFAULT&ppp12&page=2&facetexpand=[name of THAT SPECIFIC FACET such as BRAND or COLOR or PRICE]
  3. If facet has more than 10 values and there IS an input parameter such as facetexpand=BRAND, then the output schema will have the attribute of facetMoreLess = “Less” for that facet value of BRAND and the facetMoreLessUrl would be a relative URL such as v4/catalog/search?searchphrase=red dress&sortorderby=DEFAULT&ppp12&page=2. There will not need to be a facetexpand parameter in the output schema for the BRAND facet value. However for ALL the other facets not mentioned in the input param like COLOR and PRICE, they will have a similar output as Number 2 above since no input param was set for those facet values. e.g. for facet of COLOR would be: the output schema will have the attribute of facetMoreLess = “More” and facetMoreLessUrl would be a relative URL such as v4/catalog/search?searchphrase=red dress&sortorderby=DEFAULT&ppp12&page=2&facetexpand=COLOR, e.g. the output schema values for facet of PRICE would be: the output schema will have the attribute of facetMoreLess = “More” and facetMoreLessUrl would be a relative URL such as v4/catalog/search?searchphrase=red dress&sortorderby=DEFAULT&ppp12&page=2&facetexpand=PRICE.

back to top

Sample Requests and Responses

Sample Request

Request URL:

GET

http://api.macys.com/v4/catalog/search?searchphrase=red dress&sortorderby=PRICE_ASCENDING&perpage=10&page=2&imagewidth=100&upcimagewidth=100&swatchimagewidth=100

HTTP Header:

X-Macys-Webservice-Client-Id: xmj9js4jkdpe1983fmwu98gh
Accept: application/json

Sample Response

{
    "searchinput": {
        "searchphrase": "red dress",
        "sortorderby": "PRICE_ASCENDING",
        "perpage": 10,
        "page": 2,
        "inventoryassortment": "SITE",
        "imageWidth": "100",
        "upcimagewidth": "100",
        "swatchimagewidth": "100",
        "application": "ASSOCIATE",
        "device": "TABLET",
        "country": "us"
    },
    "totalpages": 19,
    "facets": [{
        "facetname": "SPECIAL_OFFERS",
        "displayname": "Special Offers",
        "facetvalues": [{
            "value": "Sales & Discounts",
            "productcount": 121
        }, {
            "value": "Clearance/Closeout",
            "productcount": 70
        }]
    }, {
        "facetname": "GENDER_AGE",
        "displayname": "Gender/Age",
        "facetvalues": [{
            "value": "Women",
            "productcount": 163
        }, {
            "value": "Teen Girls",
            "productcount": 48
        }, {
            "value": "Girls",
            "productcount": 11
        }, {
            "value": "Infant Girls",
            "productcount": 9
        }, {
            "value": "Toddler Girls",
            "productcount": 1
        }]
    }, {
        "facetname": "DRESS_OCCASION",
        "displayname": "Dress Occasion",
        "facetvalues": [{
            "value": "Casual",
            "productcount": 60
        }, {
            "value": "Party",
            "productcount": 52
        }, {
            "value": "Wear to Work",
            "productcount": 29
        }, {
            "value": "Day to Night",
            "productcount": 28
        }, {
            "value": "Evening/Formal",
            "productcount": 18
        }, {
            "value": "Guest of Wedding",
            "productcount": 13
        }, {
            "value": "Mother of the Bride",
            "productcount": 3
        }]
    }, {
        "facetname": "SPECIAL_SIZE",
        "displayname": "Special Size",
        "facetvalues": [{
            "value": "Regular",
            "productcount": 68
        }, {
            "value": "Juniors",
            "productcount": 48
        }, {
            "value": "Plus Sizes",
            "productcount": 31
        }, {
            "value": "Petites",
            "productcount": 19
        }]
    }, {
        "facetname": "SIZE_NORMAL",
        "displayname": "Size",
        "facetvalues": [{
            "value": "PXS",
            "productcount": 5
        }, {
            "value": "PS",
            "productcount": 9
        }, {
            "value": "PM",
            "productcount": 9
        }, {
            "value": "PL",
            "productcount": 7
        }, {
            "value": "PXL",
            "productcount": 3
        }, {
            "value": "XXS",
            "productcount": 2
        }, {
            "value": "XS",
            "productcount": 34
        }, {
            "value": "S",
            "productcount": 61
        }, {
            "value": "M",
            "productcount": 65
        }, {
            "value": "L",
            "productcount": 67
        }],
        "facetmoreless": "More",
        "facetmorelessurl": "/v4/catalog/search?searchphrase=red+dress&sortorderby=price_ascending&perpage=10&page=2&imagewidth=100&upcimagewidth=100&swatchimagewidth=100&facetexpand=size"
    }, {
        "facetname": "BRAND",
        "displayname": "Brand",
        "facetvalues": [{
            "value": "American Rag",
            "productcount": 13
        }, {
            "value": "Calvin Klein",
            "productcount": 13
        }, {
            "value": "Michael Kors",
            "productcount": 7
        }, {
            "value": "Ralph Lauren",
            "productcount": 7
        }, {
            "value": "Alex Evenings",
            "productcount": 5
        }, {
            "value": "Free People",
            "productcount": 5
        }, {
            "value": "GUESS?",
            "productcount": 5
        }, {
            "value": "NY Collection",
            "productcount": 5
        }, {
            "value": "Pink Rose",
            "productcount": 5
        }, {
            "value": "Rachel Rachel Roy",
            "productcount": 5
        }],
        "facetmoreless": "More",
        "facetmorelessurl": "/v4/catalog/search?searchphrase=red+dress&sortorderby=price_ascending&perpage=10&page=2&imagewidth=100&upcimagewidth=100&swatchimagewidth=100&facetexpand=brand"
    }, {
        "facetname": "COLOR_NORMAL",
        "displayname": "Color",
        "facetvalues": [{
            "value": "Multi",
            "productcount": 1
        }, {
            "value": "Red",
            "productcount": 182
        }]
    }, {
        "facetname": "DRESS_LENGTH",
        "displayname": "Dress Length",
        "facetvalues": [{
            "value": "Knee Length",
            "productcount": 71
        }, {
            "value": "Short",
            "productcount": 31
        }, {
            "value": "Long",
            "productcount": 30
        }]
    }, {
        "facetname": "SLEEVE_LENGTH",
        "displayname": "Sleeve Length",
        "facetvalues": [{
            "value": "3/4 Sleeve",
            "productcount": 10
        }, {
            "value": "Long Sleeve",
            "productcount": 5
        }, {
            "value": "One Shoulder",
            "productcount": 1
        }, {
            "value": "Short Sleeve",
            "productcount": 39
        }, {
            "value": "Sleeveless",
            "productcount": 115
        }]
    }, {
        "facetname": "PRICE",
        "displayname": "Price",
        "facetvalues": [{
            "range": {
                "torange": "50",
                "fromrange": "0"
            },
            "productcount": 86
        }, {
            "range": {
                "torange": "100",
                "fromrange": "50"
            },
            "productcount": 60
        }, {
            "range": {
                "torange": "250",
                "fromrange": "100"
            },
            "productcount": 37
        }, {
            "range": {
                "torange": "500",
                "fromrange": "250"
            },
            "productcount": 0
        }, {
            "range": {
                "fromrange": "500"
            },
            "productcount": 0
        }]
    }],
    "searchresultgroups": [{
        "totalproducts": 183,
        "products": {
            "product": [{
                "id": 830098,
                "summary": {
                    "name": "Planet Gold Juniors Dress, Short Sleeve Space-Dye A-Line",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 29,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/0/optimized/1564570_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "imagetype": "ADDITIONAL_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/4/optimized/1564574_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg"
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Green",
                    "color": "Ageless Olive",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/1/optimized/1564571_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 2,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/1/optimized/350371_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/1/optimized/350371_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Blue",
                    "color": "Denim",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/2/optimized/1564572_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 1,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1220459_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1220459_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Bicycle Red",
                    "upcadditionalimage": [{
                        "imagetype": "UPC_ADDITIONAL_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/4/optimized/1564574_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    }],
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/0/optimized/1564570_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 3,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/2/optimized/1218102_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/2/optimized/1218102_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Black",
                    "color": "Black",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1564573_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/5/optimized/1218025_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/5/optimized/1218025_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }],
                "price": {
                    "sale": {
                        "value": 19.99,
                        "label": "Sale"
                    },
                    "regular": {
                        "value": 36.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 16904,
                    "name": "Juniors",
                    "type": "rootcategory"
                }, {
                    "id": 18109,
                    "name": "Dresses",
                    "type": "homecategory"
                }, {
                    "id": 22040,
                    "name": "Juniors' Clothing",
                    "type": "sublevelcategory2"
                }]
            }, {
                "id": 779069,
                "summary": {
                    "name": "Jessica Simpson Girls Dress, Girls Tie-Dye Dress",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 158,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1430917_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "flame",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1430917_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0
                }],
                "price": {
                    "original": {
                        "value": 42.0,
                        "label": "Orig."
                    },
                    "current": {
                        "value": 19.99,
                        "label": "Now"
                    }
                },
                "category": [{
                    "id": 5991,
                    "name": "Kids",
                    "type": "rootcategory"
                }, {
                    "id": 22054,
                    "name": "GIRLS",
                    "type": "sublevelcategory2"
                }, {
                    "id": 25324,
                    "name": "Girls 7-16",
                    "type": "homecategory"
                }]
            }, {
                "id": 757818,
                "summary": {
                    "name": "BCX Juniors Dress, Strapless Sweetheart-Neck Jacquard",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 198,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1375753_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": false
                }, {
                    "imagetype": "ADDITIONAL_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/4/optimized/1375754_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "sequenceNumber": 0
                }],
                "price": {
                    "original": {
                        "value": 59.0,
                        "label": "Orig."
                    },
                    "current": {
                        "value": 19.99,
                        "label": "Now"
                    }
                },
                "category": [{
                    "id": 16904,
                    "name": "Juniors",
                    "type": "rootcategory"
                }, {
                    "id": 18109,
                    "name": "Dresses",
                    "type": "homecategory"
                }, {
                    "id": 22040,
                    "name": "Juniors' Clothing",
                    "type": "sublevelcategory2"
                }]
            }, {
                "id": 801324,
                "summary": {
                    "name": "Rare Editions Baby Dress, Baby Girls Popover Sundress with Diaper Cover",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 95,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/8/optimized/1491148_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Peach Floral",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/8/optimized/1491148_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1491149_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 1
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1491149_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 1
                }],
                "price": {
                    "sale": {
                        "value": 20.99,
                        "label": "Sale"
                    },
                    "was": {
                        "value": 24.99,
                        "label": "Was"
                    },
                    "regular": {
                        "value": 36.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 5991,
                    "name": "Kids",
                    "type": "homecategory"
                }, {
                    "id": 5991,
                    "name": "Kids",
                    "type": "rootcategory"
                }]
            }, {
                "id": 826357,
                "summary": {
                    "name": "Disney Girls Dress, Little Girls Minnie Mouse Dress",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 33,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1560857_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Red",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1560857_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0
                }],
                "price": {
                    "sale": {
                        "value": 21.99,
                        "label": "Sale"
                    },
                    "was": {
                        "value": 26.99,
                        "label": "Was"
                    },
                    "regular": {
                        "value": 36.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 5991,
                    "name": "Kids",
                    "type": "rootcategory"
                }, {
                    "id": 22054,
                    "name": "GIRLS",
                    "type": "sublevelcategory2"
                }, {
                    "id": 62970,
                    "name": "Girls 2-6X",
                    "type": "homecategory"
                }]
            }, {
                "id": 794533,
                "summary": {
                    "name": "Nautica Kids Dress, Little Girls Pleated Stripe Dress",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 33,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1560843_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Red",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1560843_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0
                }],
                "price": {
                    "sale": {
                        "value": 21.99,
                        "label": "Sale"
                    },
                    "was": {
                        "value": 28.99,
                        "label": "Was"
                    },
                    "regular": {
                        "value": 35.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 5991,
                    "name": "Kids",
                    "type": "rootcategory"
                }, {
                    "id": 22054,
                    "name": "GIRLS",
                    "type": "sublevelcategory2"
                }, {
                    "id": 62970,
                    "name": "Girls 2-6X",
                    "type": "homecategory"
                }]
            }, {
                "id": 815932,
                "summary": {
                    "name": "BeBop Juniors Dress, Cap Sleeve Lattice Cutout A-Line",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 63,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/4/optimized/1528444_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": true
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Red Gem",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/5/optimized/1528445_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 1,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/8/optimized/1218418_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/8/optimized/1218418_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Blue",
                    "color": "Peacock",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/4/optimized/1528444_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 0,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1211919_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1211919_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }],
                "price": {
                    "sale": {
                        "value": 22.99,
                        "label": "Sale"
                    },
                    "regular": {
                        "value": 39.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 16904,
                    "name": "Juniors",
                    "type": "rootcategory"
                }, {
                    "id": 18109,
                    "name": "Dresses",
                    "type": "homecategory"
                }, {
                    "id": 22040,
                    "name": "Juniors' Clothing",
                    "type": "sublevelcategory2"
                }]
            }, {
                "id": 794228,
                "summary": {
                    "name": "Pink Rose Juniors Dress, Sleeveless Striped Belted Maxi",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "customerrating": 5.0,
                    "productstartdays": 112,
                    "totalreviews": 3
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1482213_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": false
                }, {
                    "imagetype": "ADDITIONAL_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/5/optimized/1482215_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Navy/Coral",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1543227_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 3,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/0/optimized/1212870_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/0/optimized/1212870_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Orange",
                    "color": "Grey/Papaya",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/6/optimized/1543226_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 0
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 2,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/7/optimized/1219417_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 0
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/7/optimized/1219417_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 0
                }],
                "price": {
                    "sale": {
                        "value": 22.99,
                        "label": "Sale"
                    },
                    "regular": {
                        "value": 38.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 16904,
                    "name": "Juniors",
                    "type": "rootcategory"
                }, {
                    "id": 17133,
                    "name": "Juniors' BRANDS",
                    "type": "homecategory"
                }],
                "review_summary": {
                    "overallrating": 5.0,
                    "totalreviewcount": 3
                }
            }, {
                "id": 789112,
                "summary": {
                    "name": "Sugar & Spice Juniors Dress, Sleeveless Textured Lace",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "customerrating": 3.0,
                    "productstartdays": 123,
                    "totalreviews": 2
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/3/optimized/1456643_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": false
                }, {
                    "imagetype": "ADDITIONAL_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/5/optimized/1456645_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg"
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Red",
                    "color": "Red",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/8/optimized/1456648_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 2,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1456649_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 1
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/9/optimized/1456649_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 1
                }, {
                    "type": "colorwayImage",
                    "imagetype": "COLORWAY",
                    "colornormal": "Blue",
                    "color": "Teal",
                    "upcprimaryimage": {
                        "imagetype": "UPC_PRIMARY_IMAGE",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/products/0/optimized/1456650_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                        "sequenceNumber": 1
                    },
                    "swatchsequencenumber": 0,
                    "swapoutsequencenumber": 3,
                    "swatchimage": {
                        "imagetype": "SWATCH",
                        "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/1/optimized/1456651_fpx.tif?wid=100&fmt=jpeg",
                        "sequenceNumber": 1
                    }
                }, {
                    "type": "colorwayImage",
                    "imagetype": "SWATCH",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/swatches/1/optimized/1456651_fpx.tif?wid=100&fmt=jpeg",
                    "sequenceNumber": 1
                }],
                "price": {
                    "sale": {
                        "value": 22.99,
                        "label": "Sale"
                    },
                    "regular": {
                        "value": 36.0,
                        "label": "Reg."
                    }
                },
                "category": [{
                    "id": 16904,
                    "name": "Juniors",
                    "type": "rootcategory"
                }, {
                    "id": 18109,
                    "name": "Dresses",
                    "type": "homecategory"
                }, {
                    "id": 22040,
                    "name": "Juniors' Clothing",
                    "type": "sublevelcategory2"
                }],
                "review_summary": {
                    "overallrating": 3.0,
                    "totalreviewcount": 2
                }
            }, {
                "id": 826057,
                "summary": {
                    "name": "ING Plus Size Plus Size Dress, Sleeveless Colorblocked Sheath",
                    "producttype": "DRESS",
                    "onsale": true,
                    "iscollection": false,
                    "available": true,
                    "productstartdays": 60,
                    "totalreviews": 0
                },
                "image": [{
                    "imagetype": "PRIMARY_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/7/optimized/1567717_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "colorized": false
                }, {
                    "imagetype": "ADDITIONAL_IMAGE",
                    "imageurl": "http://slimages.macys.com/is/image/MCY/products/8/optimized/1567718_fpx.tif?bgc=255,255,255&wid=100&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
                    "sequenceNumber": 0
                }],
                "price": {
                    "was": {
                        "value": 33.99,
                        "label": "Was"
                    },
                    "original": {
                        "value": 49.0,
                        "label": "Orig."
                    },
                    "current": {
                        "value": 24.99,
                        "label": "Now"
                    }
                },
                "category": [{
                    "id": 32147,
                    "name": "Plus Sizes",
                    "type": "rootcategory"
                }, {
                    "id": 32915,
                    "name": "PLUS SIZE APPAREL",
                    "type": "sublevelcategory2"
                }, {
                    "id": 37038,
                    "name": "Plus Size Dresses",
                    "type": "homecategory"
                }]
            }]
        }
    }]
}

 

back to top

 

cURL Example

curl -X GET -H "x-macys-webservice-client-id: xxxxxxxxxx" -H "Accept: application/json" "http://api.macys.com/v4/catalog/search?searchphrase=red dress&sortorderby=PRICE_ASCENDING&perpage=10&page=2&imagewidth=100&upcimagewidth=100&swatchimagewidth=100"

 

 

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here

back to top

http://api.macys.com/v4/catalog/search?searchphrase=red dress&sortorderby=PRICE_ASCENDING&perpage=10&page=2&imagewidth=100&upcimagewidth=100&swatchimagewidth=100

Docs Navigation