1. Home
  2. Getting Started

Getting Started

1.1 Request access to seller integration APIs

Before use our seller integration API. You need to register as a Newegg Logistics seller at first. Please contact with Newegg Logistics team, they will guide you through the registration process.

Please refer to the PDF API Integration SOP Link to set up API –  NLS Seller API Integration SOPv2  NLS Seller API Integration SOPv2-2022

1.1.1 SSL requirements

Newegg Logistics seller integration APIs require SSL version 3.0 and higher. All calls to our seller integration APIs must be started with “https://”.

1.1.2 Get your Client ID and Client Secret

Newegg Logistics seller integration APIs use OAuth for token-based authentication and authorization. Please follow below steps to get your Client ID and Client Secret for OAuth access token generation.

  1. Log into Newegg Logistics portal (https://www.newegglogistics.com/login), find your Seller ID from Business Information tab under Manage Account > Account Setting.
  2. Send your Seller ID to Newegg Logistics support team (3PLDatafeeds@newegg.com), request them for Client ID and Client Secret.
  3. Newegg Logistics support team will take a little time to setup access permission of seller integration APIs for you, and send you the Client ID and Client Secret when

ⓘ Your Client ID and Client Secret are key information to access Newegg Logistics seller integration APIs. Please keep them in safe.

1.1.3 Generate access token

Use your Client ID and Client Secret to generate access token by sending following request to the authorization API.

POST https://apis.newegg.com/tpl/v2/authorization/generate-access-token
Accept: application/json
Content-Type: application/json

Request sample

{
"ClientID": 102690, // replace with your Client ID
"ClientSecret": "4876072742a186836f0fcffd5cbc620b", // replace with your Client Secret
"Remark": "Description of your application"
}

If your Client ID and Client Secret is valid, your will see following response with Access Token returned:

Request Sample Response

{
"AccessToken": "L3FcMWq86USjcvk6OStIz3lKYQcxDxhr46RDhYfa", // this is the access token will be used for making API calls
"ExpirationTime": "2027-07-08T12:08:15.235",
"ExpirationTimeUtc": "2027-07-08T20:08:15.235Z"
}

We will use generated access token to make API calls to Newegg Logistics seller integration APIs.


ⓘ Access token will be valid for 30 days by default, you need to re-generate a new one before the expiration time.

1.2 Making your first request

1.2.1 Request headers

You must include following headers to your API calls to our seller integration APIs.

Name Accepted Values Description
Content- Type  

application/json, application/xml

Request data format. JSON and XML format are supported.
 

Accept

 

application/json, application/xml

Response data format. JSON and XML format are supported.
 

Authorization

Bearer { Your access token here without the brace } Pass your access token prefixed with ‘Bearer ‘ in the Authorization header.

1.2.2 Base URL

All seller integration APIs are hosted under URL https://apis.newegg.com/tpl/v2/.

1.2.3 Example API call

Following is an example API call to create a new item.

POST https://apis.newegg.com/tpl/v2/item Accept: application/json
Content-Type: application/json
Authorization: Bearer L3FcMWq86USjcvk6OStIz3lKYQcxDxhr46RDhYfa

Request sample

{
"SellerPartNumber": "TEST-ITEM-001",
"Title": "TEST NLS ITEM FOR NEW ITEM CREATION",
"Manufacturer": "Newegg Logistics", "ManufacturerPartNumber": "TEST-ITEM-001", "UPC": 40076543210,
"Condition": "New", "PacksOrSets": 1,
"Length": 1.5,
"Width": 1.1,
"Height": 0.8,
"Weight": 1.58, "ShippingRestriction": false, "ContainingBatteries": false, "MSRP": 15.99,
"OriginCountries": [ "CHN
]
}

Example response (HTTP status code – 200):

{
"Succeeded": true,
"Code": "RequestSubmitted",
"Message": "Your item creation request has been submitted. The system takes about 1 minute to process your request. Item status will be changed to Active when the process is completed."
}

Example response of a bad request (HTTP status code – 400):

{
"Message": "Request validation failed.",
"Code": "ValidationErrors", "ValidationErrors": [
{
"PropertyName": "Seller Part Number",
"ErrorMessage": "'Seller Part Number' should not be empty."
}
],
"StatusCode": "BadRequest"
}

Example response of a failure API call (HTTP status code – 500):

{
"Message": "An item with the same Seller Part# already exists.",
"Code": "ItemAlreadyExists", "StatusCode": "InternalServerError"
}

1.3   Handling response errors

If your API call failed, HTTP status code 4XX or 5XX will be returned. You can use HTTP status code to check if your request was processed normally.

  • If system encountered business errors during request processing, HTTP status code 500 will be

You may need to extract error details from response content to figure out what’s wrong with it.

For POST/PUT/DELETE requests, if returned HTTP status is 200, response content will include the fields “Succeeded” and “Message”. You can check the value of field “Succeeded” to see if the request was processed normally. Refer to example below:

Request sample

{
"Succeeded": false,
"Code": "OrderCancelledAlready"
"Message": "Your order has been cancelled already, cancel order request ignored.",
}

1.3.1 Data field definition of error response

Field Type Example Value Description
 

Succeeded

 

Boolean

 

false

If HTTP status code is 200, this field will be returned to indicate if your request was processed normally.
Code String RequestCancelled Code to indicate request process result.
 

 

Message

 

 

String

Your order has been cancelled already, cancel order request ignored.  

 

Description of your request process result.

ValidationErrors Object[] List of data validation errors.
PropertyName String Seller Part Number Field name.
 

ErrorMessage

 

String

‘Seller Part Number’ should not be empty.  

Error information associated with the field.

 

StatusCode

 

String

 

InternalServerError

Description of returned HTTP status code (for 4XX, 5XX) if request was failed.

1.3.2 Used HTTP status codes

Following table lists HTTP status codes used by our seller integration APIs. Refer to HTTP/1.1: Status Code Definitions.

HTTP status code

Description

200 – OK Request was successful.
400 – Bad Request Malformed request content, or request validation failed.
401 – Unauthorized Missing Authorization header in request, or Invalid access token.
403 – Forbidden Access to the function is restricted.
404 – Not Found The resource you’re looking for does not exist.
405 – Method Not Allowed HTTP method is supported by the requested resource.
408 – Request Timeout Request timeout. You need to try again later.
409 – Conflict Resource already exists, or there is a conflict with its current state.
 

422 – Unprocessed Entity

System is unable to process your request. Please check the response message for details.

Not defined in RFC 2616, reserved for future use.

500 – Internal Server Error System encountered some unexpected errors during request processing. Please try again later.
503 – Service Unavailable Cannot reach the Newegg API gateway. You need to try again later.
504 – Gateway Timeout System is busy, Newegg API gateway was unable to send you the response in time. You may need to try again later, or report the issue to Newegg Logisitcs support team if the problem still exists.

1.3.3 Common used error codes

 

Code

Status Code  

Description

 

UnexpectedError

 

500

We are experiencing technical difficult to process your request at this time. We apologize for the inconvenience and please try again later.
ValidationErrors 400 Request validation failed.
AuthorizationRequired 401 Authorization failed. Please check your access token.
 

SellerAccountSuspended

 

403

Sorry, your account is temporarily suspended because you didn’t pay an invoice in time as agreed.
 

SellerAccountDisabled

 

403

Sorry, your cannot perform this operation, because your account was disabled.
SellerAccountClosed 403 Sorry, your seller account was closed.
SellerAccountTerminated 403 Sorry, your seller account was terminated.
SellerAccountNotActivated 403 Sorry, your seller account is not activated yet.

1.4 Date and time zone

Newegg Logistics seller integration APIs accept ISO 8601 for date time values. Default time zone is PST/PDT if not specified. Following table shows valid date time values for your reference.

Date time value Time zone
2019-08-30 15:00:00
2019-08-30 15:00:00.149

2019-08-30 15:00:00.1493902

PST/PDT
2019-08-30 15:00:00.1493902-07:00
2019-08-30T15:00:00
2019-08-30T15:00:00.149

2019-08-30T15:00:00.1493902

PST/PDT
2019-08-30T15:00:00.1493902-07:00
2019-08-30T22:00:00Z
2019-08-30T22:00:00.149Z UTC
2019-08-30T22:00:00.1493902Z
2019-08-30T22:00:00+08:00
2019-08-30T22:00:00.149+08:00 +08:00 (Beijing)

Date time value in response will be serialized as yyyy-MM-dd’T’HH:mm:ss.fff and yyyy-MM- dd’T’HH:mm:ss.fff’Z’ (for UTC) format by default. For example:

  • 2029-07-20T11:29:48.263
  • 2029-07-20T03:29:48.263Z

1.5 Testing with sandbox seller

Newegg Logistics created a public sandbox seller for testing purpose. You can use this sandbox seller to testing your integration with Newegg Logistics.

Sandbox User ID ADFS
Sandbox User ID nls_testing@hotmail.com
Sandbox User Password 4NLSTesting
Client ID 102690
Client Secret 4876072742a186836f0fcffd5cbc620b
Access Token m2f00zGdEKlR6wXV64b4QtwJOEc5JJge1cn7xX8C

Your use above sandbox user ID and password to log into Newegg Logistics portal (https://www.newegglogistics.com/login), to check your testing data submitted by your application.

ⓘ Other developers may use the sandbox account for testing at same time. In order to avoid modifying testing data of the others, we suggest you create your own testing orders with your own test items.