Product Detail (Using UPC) V4
- Description
- Request URL
- Path and Query Parameters
- Sample Requests and Responses
- cURL Examples
- Error Codes
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))
HTTP Method and Request URL
GET
https://api.macys.com/v4/catalog/product/upc/[upcID](object(nestedobject))
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 |
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 }] }] }
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:
Docs Navigation
- Overview
- Customer Services
- Common API Characteristics
- Ad Media
- Catalog Services
- Order Services
- Mobile Utilities
- Promotion and Coupon Services
- Registry Services
- Review Services
- Store Services
- User Services
- Error Handling
- Deprecated Services
- Macy's API FAQ
- BOPS Stores
- What's New