• Register

Product Detail (Using UPC) V4

Description

The format of the URL for the V4 service has greatly changed from V3 to V4.  Instead of using a Parameter=Value the logic includes nested attributes that control the content returned for a product.  For instance, in V3 the show parameter was used and if this parameter was not defined we returned default results based on default Vales.  You then could use the "show" parameter to specify what specific attributes you wanted. Ex: http://api.macys.com/v3/catalog/product?upc=50946872827&show=price

In v4 you return the items by listing the items in braces where you follow the logic of the nested objects.  For instance the productdetails object includes the following nested objects:"sizemap, colormap,typemap, domainvaluesmap, price, summary, badges, collection, childproducts, masterproducts, shipping, attributes, primaryimage, additionalimages, brand, corpclass, availability, urlmetadata"  So to make the same kind of call as above using V4 service you would format you URL as follows:  Ex: http://api.macys.com/v4/catalog/product/upc/50946872827(productdetails(price))

back to top

HTTP Method and Request URL

GET

https://api.macys.com/v4/catalog/product/upc/[upcID](object(nestedobject))

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

Path Parameters

Parameter

Description

Mandatory

Sample Value

upcID

Unique ID for each UPC. Multiple upcIDs can be sent in one call by using a comma separator

optional, but you need at least upcNumber or productId.

50946872827,50946872831

Object Parameters

Object

Nested Object

Description

Mandatory

Sample Value
productdetails

 

sizemap, colormap,typemap, domainvaluesmap, price, summary, badges, collection, childproducts, masterproducts, shipping, attributes, primaryimage, additionalimages, brand, corpclass, availability, urlmetadata This object includes 15 nested objects. If no nested objects are specified we return them all. You can select one nested object or multiples. If you include multiples, seperate them by commas.

 

No (productdetails(price,summary))
upcs upcdetails Returns UPC details No (upcs(upcdetails))
productcategory No (productcategory)
reviews Up to 10 reviews are returned No (reviews)
rebates Returns any rebates for product No (rebates)
promotions Returns any promotions for product No (promotions)
storeCouponData StoreNumber, upc,dealEligable, uycCoupon, beforeUycPrice, uvySavingsTotal, afterUycPrice, uycDisocuntType, uycDiscount, Success Returns store coupon data for a specific UPC and new pricing information once store coupon is applied to purchase. No (storeCouponData)
categoryids Returns all category ID's for the product No (categoryids)
storedetails Returns store details based on the storenumber query parameters No (storedetails)

 

Query Parameters

Parameter

Description

Mandatory

Sample Value

retrieveallupcs Retrieves all upcs including inactive or unavailable upcs No true or false
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 magicofmacysap
storenumber Required when requesting storedetails No 10

 

 

 

back to top

Sample Requests and Responses

Sample Requests

Request URL:

GET

https://api.macys.com/v4/catalog/product/upc/50946872827(productdetails(price,summary,availability),promotions,rebates)

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

Sample Response

{
    "product": [{
        "id": 77589,
        "productDetails": {
            "summary": {
                "name": "KitchenAid KSM150PS Artisan 5 Qt. Stand Mixer",
                "productURL": "http://www1.macys.com/shop/product/kitchenaid-ksm150ps-artisan-5-qt-stand-mixer?ID=77589",
                "description": "Retro styled and easy to use, the KitchenAid Artisan stand mixer is the perfect kitchen companion. Employing a unique tilting head to facilitate bowl and content removal, this mixer is undeniably handy. 1-year hassle-free replacement warranty. Model KSM150PS. ",
                "typeName": "MIXER",
                "available": true,
                "productStartDays": 1388,
                "metricNumberOfReviews": 994,
                "isNew": false,
                "taxwareCode": 91000,
                "productGroup": false,
                "checkInStoreEligibility": true,
                "maxQuantity": 6,
                "bullets": ["Imported", "Includes flat beater, wire whip, dough hook, pouring shield and polished bowl with handles", "Mirror-polished stainless steel mixing bowl features an extra-large 5-qt. capacity and ergonomic handle", "Average capacity: nine cups of flour", "Prepare up to four loaves of bread, nine dozen cookies or seven pounds of mashed potatoes", "Powerful 325-watt motor effectively mixes even the toughest dough and batter", "Pouring shield reduces mess by channeling ingredients into bowl", "Measures 13.9\" x 8.7\" X 14.1\""],
                "comparable": true,
                "active": true,
                "defaultCategoryId": 7554,
                "giftWrappable": false,
                "visible": true,
                "clearanceStartDays": 16155,
                "countryEligible": true,
                "primaryPortraitSource": "397865_fpx.tif",
                "additionalImageSource": ["2027761_fpx.tif", "2072718_fpx.tif"],
                "rebateId": ["600377"]
            },
            "price": {
                "retail": {
                    "pricevalue": {
                        "low": 499.99
                    }
                },
                "original": {
                    "pricevalue": {
                        "low": 499.99
                    }
                },
                "pricetype": 0,
                "onsale": false
            },
            "availability": {
                "available": true
            }
        },
        "promotions": [{
            "promotionID": 19832602,
            "promotionType": "Percent Off Order",
            "offerDescription": "EXTRA 10% OFF Electrics! CODE: BLOOM",
            "description": "EXTRA 10% OFF All Kitchen Electrics with promo code BLOOM! Offer ends Sunday, March 30th.",
            "attributes": [{
                "name": "BADGE_TEXT",
                "values": [{
                    "value": "EXTRA 10% OFF",
                    "seqnum": 1
                }]
            }],
            "promotionCode": "BLOOM"
        }],
        "rebates": [{
            "text": "Purchase a KitchenAid 5 Qt Artisan Standmixer (KSM150 or KSM155) & receive a $30 MIR. ",
            "description": "Purchase a KitchenAid 5 Qt Artisan Standmixer (KSM150 or KSM155) & receive a $30 MIR.",
            "mediaGroupID": 600377
        }]
    }]
}

back to top

cURL Examples

curl -X GET -H "x-macys-webservice-client-id: xxxxxxxxxxx" -H "Accept: application/json" "https://api.macys.com/v4/catalog/product/upc/50946872827(productdetails(price,summary,availability),promotions,rebates)"

 

 

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here

back to top

Docs Navigation