Item Ranking API Guide

1.1 Get Item Ranking

Get the item’s ranking data including buy box information and sales ranking information.

1.1.1 Resource URL & Information

Resource URL

https://api.newegg.com/marketplace/contentmgmt/item/ranking?sellerid={sellerid}
https://api.newegg.com/marketplace/b2b/contentmgmt/item/ranking?sellerid={sellerid}
https://api.newegg.com/marketplace/can/contentmgmt/item/ranking?sellerid={sellerid}

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.
Only Account Managers can help a seller to access this.
Only accounts that are eligible have Account Managers.

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 &amp; 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

https://api.newegg.com/marketplace/contentmgmt/item/review?sellerid={sellerid}
https://api.newegg.com/marketplace/b2b/contentmgmt/item/review?sellerid={sellerid}
https://api.newegg.com/marketplace/can/contentmgmt/item/review?sellerid={sellerid}

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]"
    }
]