• Register

Review v1 Reviews

Description

Returns all customers' reviews for the specified product(s).

HTTP Method and Request URL

GET

http://api.macys.com/review/v1/reviews?prodId=[productId]&_fields=[fields]&_offset=[offset]&_limit=[limit]&_sortby=[columnname]&_sortorder=[order]&moderationStatus=[status]&approvedTopRated=[flag]&includeOtherReviewsByUser=[flag]&otherReviewsByUserCount=[count]

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. 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

prodId

Product id to get reviews for. 
NOTE: Multiple product IDs are not supported.

 yes 828
_fields
 Expression of what fields should be returned. 
Syntax: field-name-1,field-name-2,...,complex-field-name-1(sub-field-name-1,...),...
 no

reviewerId,rating
_offset

Part of pagination mechanism. Specifies the offset to count the records from.

For correct pagination through all the records it's best to use "next" link which is given in the response of request

 no

1
_limit Part of pagination mechanism. Specifies the page size. no

8
_sortby Part of the ordering mechanism. Specifies the column to sort by. 
The value should be one of: submissionTime, rating, reviewText, topContributor, videos, featured. 
NOTE: If the "reviewText" column is specified, the ordering is performed by review text length (but not with lexicographical comparison of review text itself). If the "videos" column is specified, only presence or absence of videos is taken into account.		 no

submissionTime,topContributor
_sortorder It's a part of the ordering mechanism. Specifies the sorting order. 
Only ASCENDING and DESCENDING values are possible.		 no

ASCENDING or DESCENDING
moderationStatus Specifies to filter reviews by moderation status. 
The value should be one of: NONE, SUBMITTED, APPROVED, HOLD, PENDING, REJECTED, REMOVEDBYCLIENT, REMOVEDTEST, AUTOMATEDHOLD, EXPIRED		 no

SUBMITTED
approvedTopRated Specifies to filter and return one latest top rated review for product. Review is recognized as top rated if it: APPROVED, has enough review text length AND enough rating 
The value should be true and when this query parameter is specified, this takes precedence and all the other query parameters except 'prodId' will not have any impact		 no

true or false
includeOtherReviews ByUser Specifies to include information about other the most recent and approved reviews of the reviewer. no

true or false
otherReviewsByUserCount Specifies the number of other reviews of the reviewer to include. no

8

back to top

Sample Request and Response

Sample Request

Request URL:

GET

http://api.macys.com/review/v1/reviews?prodId=828&_offset=3

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

Sample Response

{
  "reviews": {
    "review": [
      {
        "id": 155275039,
        "reviewerId": "4992991483",
        "displayName": "Marypaty",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "Great color",
        "reviewText": "The color is perfect for my green eyes as they lose with clear shadows I use and I really enlarges the eyes.",
        "rating": 3,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "displayLocale": "en_US",
        "submissionTime": "2016-07-12T16:46:02.000",
        "productReviewsURL": "http://reviews.macys.com/7129/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=155275039",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-07-12T17:15:22.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": []
      },
      {
        "id": 155015716,
        "reviewerId": "417291621",
        "displayName": "ldb924",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "Amazing",
        "reviewText": "The only liquid eyeliner I use, the liner is easy to use and never flakes.",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "displayLocale": "en_US",
        "submissionTime": "2016-07-08T16:01:05.000",
        "productReviewsURL": "http://reviews.macys.com/7129/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=155015716",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-07-08T16:30:33.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": []
      },
      {
        "id": 152061402,
        "reviewerId": "710102077",
        "displayName": "MartyPlusGirl",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "I love it!",
        "reviewText": "Love this eyeliner!  It goes on smooth, and stays on for hours without fading.  I am not one to be very precise with my makeup, but this eyeliner makes it super easy to create lovely looks.  I look like a pro!  I even got one for my teenage niece as a Birthday present, so she can practice and she loves it.",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "displayLocale": "en_US",
        "submissionTime": "2016-06-01T20:40:00.000",
        "productReviewsURL": "http://reviews.macys.com/7129/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=152061402",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-06-01T21:00:12.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": []
      },
      {
        "id": 149928486,
        "reviewerId": "274025848",
        "displayName": "JoA425",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "Perfection",
        "reviewText": "I've tried many a liquid eyeliner, but this is by far them best!",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "displayLocale": "en_US",
        "submissionTime": "2016-04-22T13:35:19.000",
        "productReviewsURL": "http://reviews.macys.com/7129/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=149928486",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-04-22T14:00:19.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": []
      },
      {
        "id": 149635617,
        "reviewerId": "1424088490",
        "displayName": "shenurse",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "wonderful and precise eyeliner!!",
        "reviewText": "Can't get any better than Lancome and the masscara and eyeliner. I have several colors and was really looking for the brighter blue eyeliner and could not find it (hope they did not discontinue it!!!) settled for the navy and it doesn't dissappoint, but i did want a brighter color. I have a shaky hand and this helps me to draw a clean and near perfect line. Definitely reccommend!",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "reviewerLocation": "California",
        "displayLocale": "en_US",
        "submissionTime": "2016-04-17T16:17:10.000",
        "productReviewsURL": "http://reviews.macys.com/7129aa/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=149635617",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-04-19T16:15:27.000",
        "ratingRange": 5,
        "profile": {
          "reviewerAgeRange": "50-60",
          "reviewerGender": "Female",
          "reviewerShoppingFrequency": "Frequently"
        },
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": [
          {
            "id": "Wear",
            "label1": "Natural wear",
            "label2": "Long lasting",
            "ratingRange": 7,
            "ratingValue": 7
          }
        ]
      },
      {
        "id": 147720857,
        "reviewerId": "568066602",
        "displayName": "lulululululu",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "best color eyeliner",
        "reviewText": "I have searched for this color and the saleslady was so nice she looked for it in all macys stores and had it shipped to me free",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 1,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 1,
        "displayLocale": "en_US",
        "submissionTime": "2016-03-18T11:51:44.000",
        "productReviewsURL": "http://reviews.macys.com/7129aa/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=147720857",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-03-21T01:23:39.000",
        "ratingRange": 5,
        "profile": {
          "reviewerAgeRange": "Over 60",
          "reviewerGender": "Female",
          "reviewerShoppingFrequency": "Occasionally"
        },
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": [
          {
            "id": "SheerBold",
            "label1": "Sheer",
            "label2": "Bold",
            "ratingRange": 7,
            "ratingValue": 5
          },
          {
            "id": "Oil",
            "label1": "Oil-absorbing",
            "label2": "Moisturizing",
            "ratingRange": 7,
            "ratingValue": 1
          },
          {
            "id": "Wear",
            "label1": "Natural wear",
            "label2": "Long lasting",
            "ratingRange": 7,
            "ratingValue": 7
          }
        ]
      },
      {
        "id": 146767802,
        "reviewerId": "10724208530",
        "displayName": "Beecreekfarm",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "Great product",
        "reviewText": "Easy to use and stays on great. I was looking for a product that does both now I've found it....",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "displayLocale": "en_US",
        "submissionTime": "2016-03-05T01:09:43.000",
        "productReviewsURL": "http://reviews.macys.com/7129aa/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=146767802",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-03-07T00:45:10.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": []
      },
      {
        "id": 146716582,
        "reviewerId": "9879253941",
        "displayName": "NonnaVC",
        "anonymous": false,
        "ratingsOnly": false,
        "titleOfReview": "Buy it!!",
        "reviewText": "No other product line can compare. I have tried other brands but always come back to the best!!!",
        "rating": 5,
        "recommended": true,
        "numFeedbacks": 0,
        "numPositiveFeedbacks": 0,
        "numNegativeFeedbacks": 0,
        "reviewerLocation": "California",
        "displayLocale": "en_US",
        "submissionTime": "2016-03-04T12:47:57.000",
        "productReviewsURL": "http://reviews.macys.com/7129/828/lancome-artliner-precision-point-eyeliner-reviews/reviews.htm?reviewID=146716582",
        "featured": false,
        "moderationStatus": "APPROVED",
        "lastModificationDate": "2016-03-06T13:15:14.000",
        "ratingRange": 5,
        "profile": {},
        "topContributor": false,
        "link": [
          {
            "rel": "product",
            "ref": "http://32.83.67.26:80/api/catalog/v2/products/828"
          }
        ],
        "photos": [],
        "videos": [],
        "sliders": [
          {
            "id": "Wear",
            "label1": "Natural wear",
            "label2": "Long lasting",
            "ratingRange": 7,
            "ratingValue": 4
          }
        ]
      }
    ],
    "link": [
      {
        "rel": "self",
        "ref": "http://32.83.67.26:80/api/review/v1/reviews?sdpGrid=cellA&prodId=828&_offset=3"
      },
      {
        "rel": "first",
        "ref": "http://32.83.67.26:80/api/review/v1/reviews?prodId=828&_offset=0&sdpGrid=cellA"
      },
      {
        "rel": "previous",
        "ref": "http://32.83.67.26:80/api/review/v1/reviews?prodId=828&_offset=0&sdpGrid=cellA"
      },
      {
        "rel": "next",
        "ref": "http://32.83.67.26:80/api/review/v1/reviews?prodId=828&_offset=11&sdpGrid=cellA"
      },
      {
        "rel": "last",
        "ref": "http://32.83.67.26:80/api/review/v1/reviews?prodId=828&_offset=283&sdpGrid=cellA"
      }
    ]
  }
}

 

cURL Example

curl -X GET -H "X-Macys-Webservice-Client-ID: XXXXXXXX" -H "Accept: application/json" "http://api.macys.com/review/v1/reviews?prodId=828&_offset=3"

 

 

 

back to top

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here

back to top

version 11 as of 8 years ago by Damian Bennett

Docs Navigation