Item Ranking API Guide
Get the item’s ranking data including buy box information and sales ranking information.
1.1.1 Resource URL & Information
Resource URL
Note: Please make sure your request URL is all in lower case (except for Seller ID) and cannot contain any blank spaces or line breaks.
Parameters
| Name | Required? | Description |
| sellerid | Yes | Your seller ID on Newegg Marketplace |
Resource Information
| HTTP Method | Authentication? | Request Formats | Response Formats | Rate Limited? |
| POST | Required | XML, Json | XML, Json | 1000 per min per client |
1.1.2 Request Body
| Attribute | Required? | Format | Description | |
| ContentQueryCriteria
|
Type | No | Integer | Available values:
0: NE Item# 1: Seller Part# 2: UPC Code Note: If left blank, default value will be Seller Part#. |
| Values | Yes | Array | A string array according to specified type | |
| CountryCode | No | String | Ship to Country (only for USA global country).
Note: If left blank, default value will be platform newegg.com =>USA neweggBusiness.com=>B2B newegg.ca=>CAN |
|
Example: XML, Request
POST http://apis.newegg.com/marketplace/contentmgmt/item/ranking?SellerId={SellerID}
Authorization: 720ddc067f4d115bd544aff46bc75634
SecretKey: 21EC2020-3AEA-1069-A2DD-08002B30309D
Content-Type: application/xml
Accept: application/xml
<ContentQueryCriteria>
<Type>0</Type>
<Values>
<Key>9SIA88880000001</Key>
<Key>9SIV88880000002</Key>
</ContentQueryCriteria>
Example: Json, Request
http://apis.newegg.com/marketplace/contentmgmt/item/ranking?SellerId={SellerID}Authorization: 720ddc067f4d115bd544aff46bc75634
SecretKey: 21EC2020-3AEA-1069-A2DD-08002B30309D
Content-Type: application/json
Accept: application/json
{
"type": 0,
"values": [
"9SIA88880000001",
"9SIA88880000002"
]
}
|
1.1.3 Response Body
| Attribute | Format | Description | ||||||
| NeweggAPIResponse | IsSuccess | Boolean | True or False | |||||
| OperationType | String | GetItemRank | ||||||
| SellerID | String | Your Seller ID | ||||||
| ResponseDate | Datetime | The Response Date Time | ||||||
| ResponseBody | ItemRankResponse | Item | String | Newegg Item Number, the item you requested | ||||
| ItemList | RankItem | IsMyItem | Boolean | True or False, True means the item belongs to you | ||||
| ItemNumber | String | Newegg Item Number, the item related to your request | ||||||
| ItemCondition | String | Item’s Condition: New/Refurbished/Used | ||||||
| UnitPrice | String | |||||||
| SellingPrice | String | The finial price shows on website | ||||||
| Discount | String | Discount | ||||||
| Shipping | String | Shipping Charge | ||||||
| IsBuyBoxWinner | Boolean | True or False, True = Buy Box Winner. | ||||||
| IsBrandOwner | Boolean | True or False, True = the item’s owner is a brand owner | ||||||
| IsShipByNewegg | Boolean | True or False, True = the item is shipped by Newegg | ||||||
| SellerRating | String | Seller’s rating | ||||||
| BuyBoxRank | String | If the seller wins the buy box the ranking will be 1, others will be 2/3/4. | ||||||
| SalesRanking | CategoryName | String | The category name shows on website. | |||||
| SubcategoryName | String | The subcategory name when you create this item | ||||||
| Ranking | String | The item’s Ranking in this Category. | ||||||
Example: XML, Response
<?xml version="1.0" encoding="utf-16"?> <NeweggAPIResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <IsSuccess>true</IsSuccess> <OperationType>GetItemRank</OperationType> <SellerID>A888</SellerID> <ResponseDate>2023-06-10T00:47:28.7840738-07:00</ResponseDate> <ResponseBody> <ItemRankResponse> <Item>9SIA888HGT2794</Item> <ItemList> <RankItem> <IsMyItem>true</IsMyItem> <ItemNumber>9SIA88880000001</ItemNumber> <ItemCondition>New</ItemCondition> <UnitPrice>26.0</UnitPrice> <SellingPrice>26.0</SellingPrice> <Discount>0.0</Discount> <Shipping>0.01</Shipping> <IsBuyBoxWinner>true</IsBuyBoxWinner> <IsBrandOwner>false</IsBrandOwner> <IsShipByNewegg>false</IsShipByNewegg> <SellerRating /> <SalesRanking> <CategoryName /> <SubcategoryName>Cases & Covers</SubcaegoryName> <Ranking /> </SalesRanking> <BuyBoxRank>1</BuyBoxRank> </RankItem> </ItemList> </ItemRankResponse> </ResponseBody> </NeweggAPIResponse>
Example: Json, Response
{
"ResponseBody": [
{
"Item": "9SIA88880000001",
"ItemList": [
{
"IsMyItem": true,
"ItemNumber": "9SIA88880000001",
"ItemCondition": "New",
"UnitPrice": "26.0",
"SellingPrice": "26.0",
"Discount": "0.0",
"Shipping": "0.01",
"IsBuyBoxWinner": true,
"IsBrandOwner": false,
"IsShipByNewegg": false,
"SellerRating": "",
"SalesRanking": {
"CategoryName": "",
"SubcategoryName": "Cases & Covers",
"Ranking": ""
},
"BuyBoxRank": "1"
}
]
}
],
"IsSuccess": true,
"OperationType": "GetItemRank",
"SellerID": "A888",
"ResponseDate": "2023-06-10T00:41:58.5159436-07:00"
}
1.1.4 Request Failure Errors
For common HTTP error responses, please refer to Common Error Responses
| Error Code | Description |
| CT001 | Invalid ItemNumber |
| CT002 | Invalid SellerPartNumber |
| CT003 | Invalid UPCCode |
| CT099 | Internal Error |
Example: XML, Response
<?xml version="1.0" encoding="utf-8"?> <Errors xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Mkpl.Sdk.Core.Api.Entity"> <Error> <Code>CT002</Code> <Message>Invalid SellerPartNumber.[9SIA88880000001,9SIV88880000002]</Message> </Error> </Errors>
Example: Json, Response
[
{
"Code": "CT002",
"Message": "Invalid SellerPartNumber.[9SIA88880000001,9SIV88880000002]"
}
]
1.2 Get Item Reviews
Get the item review data.
1.2.1 Resource URL & Information
Resource URL
Note: Please make sure your request URL is all in lower case (except for Seller ID) and cannot contain any blank spaces or line breaks.
Parameters
| Name | Required? | Description |
| sellerid | Yes | Your seller ID on Newegg Marketplace |
Resource Information
| HTTP Method | Authentication? | Request Formats | Response Formats | Rate Limited? |
| POST | Required | XML, Json | XML, Json | 1000 per min per client |
1.2.2 Request Body
| Attribute | Required? | Format | Description | |
| ContentQueryCriteria | Type | Yes
|
Integer | 0: NE Item#
1: Seller Part# Note: If left blank, default value will be Seller Part# |
| Value | Yes | String | A string according to a given inquiry type | |
| DateFrom | No | Datetime | Date From (Pacific Standard Time) Please refer to the Acceptable Date Format –default is last 3 month start date. |
|
| DateTo | No | Datetime | Date To (Pacific Standard Time)
Please refer to the Acceptable Date Format –default is current date. |
|
| PageIndex | No | Integer | Current page index
If left blank, will use 1 as default. |
|
| PageSize | No | Integer | Return records count in one page. (Max is 20 per page)
If left blank, will use 10 as default. |
|
Example: XML, Request
POST https://api.newegg.com/marketplace/contentmgmt/item/review?sellerid={SellerID}
Authorization: 720ddc067f4d115bd544aff46bc75634
SecretKey: 21EC2020-3AEA-1069-A2DD-08002B30309D
Content-Type: application/xml
Accept: application/xml
<ContentQueryCriteria>
<Type>0</Type>
<Value>9SIV88880000001</Value>
<DateFrom>2023-01-01</DateFrom>
<DateTo>2023-06-26</DateTo>
<PageSize>20</PageSize>
<PageIndex>1</PageIndex>
</ContentQueryCriteria>
Example: Json, Request
POST https://api.newegg.com/marketplace/contentmgmt/item/review?sellerid={SellerID}
Authorization: 720ddc067f4d115bd544aff46bc75634
SecretKey: 21EC2020-3AEA-1069-A2DD-08002B30309D
Content-Type: application/json
Accept: application/json
{
"Type": 0,
"Value": "9SIV88880000001",
"DateFrom": "2023-01-01",
"DateTo": "2023-06-26",
"PageSize": 20,
"PageIndex": 1
}
1.2.3 Response Body
| Attribute | Format | Description | |||||
| NeweggAPIResponse | IsSuccess | Boolean | True or False | ||||
| OperationType | String | GetItemReview | |||||
| SellerID | String | Your Seller ID | |||||
| ResponseDate | Datetime | The Response Date Time | |||||
| ResponseBody | ItemNumer | String | The request item number | ||||
| ReviewList | ReviewItem | Title | String | The review titles | |||
| Ranking | Decimal | The review ranking | |||||
| Date | Datetime | The review created date | |||||
| Comments | Pros | String | Pros | ||||
| Cons | String | Cons | |||||
| Overall | String | Overall | |||||
| PageInformation | TotalCount | Integer | Total review count of the requested item | ||||
| TotalPageCount | Integer | Total Page Count | |||||
| PageSize | Integer | Page Size | |||||
| PageIndex | Integer | Current Page number | |||||
Example: XML, Response
<?xml version="1.0" encoding="utf-16"?> <NeweggAPIResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <IsSuccess>true</IsSuccess> <OperationType>GetItemReview</OperationType> <SellerID>A888</SellerID> <ResponseDate>2023-06-10T02:09:57.7802701-07:00</ResponseDate> <ResponseBody> <ItemNumer>9SIV88880000001</ItemNumer> <ReviewList> <ReviewItem> <Title>Crashing during game</Title> <Ranking>1</Ranking> <Comments> <Pros>Good while it lasted</Pros> <Cons>Pc isnt even a month old. Worked good one day and the next day I could not play any games without the game crashing or my monitor cutting off randomly. There are also times were my whole PC cut off. Everything checks out so Im not sure of the problem.</Cons> <Overall>All Reviews</Overall> </Comments> <Date>2023-05-23T01:48:01.46</Date> </ReviewItem> <ReviewItem> <Title>First PC, and very satisfied.</Title> <Ranking>2</Ranking> <Comments> <Pros>-Packaged well\n-Worked right out of the box\n-Very fast\n-Cool lighting options\n-Runs several tasks simultaneously and without performance issues\n-Easy to set up and get going\n-Runs Warzone and Discord flawlessly \n-Good quality accessories </Pros> <Cons>-None so far</Cons> <Overall>All Reviews</Overall> </Comments> <Date>2023-05-23T01:47:52.27</Date> </ReviewItem> </ReviewList> <PageInformation> <PageIndex>1</PageIndex> <PageSize>20</PageSize> <TotalCount>10</TotalCount> <TotalPageCount>1</TotalPageCount> </PageInformation> </ResponseBody> </NeweggAPIResponse>
Example: Json, Response
{
"ResponseBody": {
"ItemNumer": "9SIV88880000001",
"ReviewList": [
{
"Title": "Crashing during game",
"Ranking": 1.0,
"Comments": {
"Pros": "Good while it lasted",
"Cons": "Pc isnt even a month old. Worked good one day and the next day I could not play any games without the game crashing or my monitor cutting off randomly. There are also times were my whole PC cut off. Everything checks out so Im not sure of the problem.
",
"Overall": "All Reviews"
},
"Date": "2023-05-23T01:48:01.46"
},
{
"Title": "First PC, and very satisfied.",
"Ranking": 2.0,
"Comments": {
"Pros": "-Packaged well\n-Worked right out of the box\n-Very fast\n-Cool lighting options\n-Runs several tasks simultaneously and without performance issues\n-Easy to set up and get going\n-Runs Warzone and Discord flawlessly \n-Good quality accessories.",
"Cons": "-None so far",
"Overall": "All Reviews"
},
"Date": "2023-05-23T01:47:10.36"
}
],
"PageInformation": {
"PageIndex": 1,
"PageSize": 20,
"TotalCount": 10,
"TotalPageCount": 1
}
},
"IsSuccess": true,
"OperationType": "GetItemReview",
"SellerID": "A888",
"ResponseDate": "2023-06-10T02:07:37.0911403-07:00"
}
1.2.4 Request Failure Errors
For common HTTP error responses, please refer to Common Error Responses
| Error Code | Description |
| CT001 | Invalid ItemNumber |
| CT002 | Invalid SellerPartNumber |
| CT099 | Internal Error |
Example: XML, Response
<?xml version="1.0" encoding="utf-8"?> <Errors xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Mkpl.Sdk.Core.Api.Entity"> <Error> <Code>CT002</Code> <Message>Invalid SellerPartNumber.[9SIV88880000001]</Message> </Error> </Errors>
Example: Json, Response
[
{
"Code": "CT002",
"Message": "Invalid SellerPartNumber.[9SIA88880000001]"
}
]