@bizon/mws-sdk
v6.0.1
Published
SDK for Amazon Marketplace Web Services
Downloads
39
Maintainers
Readme
mws-sdk
SDK for Amazon Marketplace Web Services
🚀 Switching to the Selling Partner API? See our modularized SDK library for Amazon Selling Partner API (fully typed in TypeScript).
CI
Getting started
npm install --save @bizon/mws-sdk
Usage
const MWSClient = require('@bizon/mws-sdk')
const client = new MWSClient({
accessKeyId: '', // defaults to process.env.MWS_ACCESS_KEY_ID
secretAccessKey: '', // defaults to process.env.MWS_SECRET_ACCESS_KEY
sellerId: '',
mwsToken: '',
mwsRegion: ''
})
Region and Marketplaces
The MWS documentation defines a list of regions and marketplaces available in each region.
The marketplaces in a region do not all share a common API endpoint, so this library defines a new concept of MWS region, based on the API endpoint. Here’s the list of the available MWS regions:
Generic MWS regions:
Region | API Endpoint | Name -------|--------------|----- na | mws.amazonservices.com | North America eu | mws-eu.amazonservices.com | Europe fe | mws-fe.amazonservices.com | Far East
Country specific MWS regions:
Region | API Endpoint | Name -------|--------------|----- ca | mws.amazonservices.ca | Canada mx | mws.amazonservices.com.mx | Mexico ae | mws.amazonservices.ae | United Arab Emirates in | mws.amazonservices.in | India jp | mws.amazonservices.jp | Japan au | mws.amazonservices.com.au | Australia
This library also allows to specify a list of marketplaces (either 2 letter country codes, marketplace IDs or domains) so you can restrict API calls to your marketplace participations:
const client = new MWSClient({
accessKeyId: '',
secretAccessKey: '',
sellerId: '',
mwsToken: '',
marketplaces: [
'A1F83G8C2ARO7P', // UK
'fr',
'Amazon.it'
]
})
Keep in mind that the specified marketplaces will have to be in the same MWS region, otherwise an error will be thrown.
Pagination
The MWS API defines multiple API calls for pagination. They have been abstracted in this SDK. Whenever there are more retrievable results, a nextToken
property will be available in the operation’s result. The nextToken
can then be used as an option of that same operation to fetch an additional page.
let nextToken
do {
const result = await client.orders.listOrders({
nextToken, // If nextToken is truthy, all the other options are ignored.
lastUpdatedAfter: new Date(2020, 0, 1)
})
nextToken = result.nextToken
} while (nextToken)
Error handling
Whenever the MWS API returns a non-OK HTTP status, a MWSError
will be thrown. Use error.body
to inspect the contents of the error, and error.response
to access the raw HTTP response.
const {MWSError} = require('@bizon/mws-sdk')
try {
const result = await client.products.getLowestPricedOffersForSku({
marketplaceId: 'A1F83G8C2ARO7P',
sellerSku: 'some-sku',
itemCondition: 'new'
})
} catch (error) {
if (error instanceof MWSError) {
console.log(error.sellerId)
console.log(error.marketplaces)
console.log(error.body) // This will contain the parsed XML body
console.log(error.response.statusCode)
}
}
API
Finances
Example:
const result = await client.finances.listFinancialEventGroups({
financialEventGroupStartedAfter: new Date(2015, 2, 1),
financialEventGroupStartedBefore: new Date(2015, 4, 1)
})
Options:
Name | Type | Default
-----|------|--------
maxResultsPerPage | Number
| 100
financialEventGroupStartedAfter | Date
|
financialEventGroupStartedBefore | Date
|
nextToken | String
|
Example:
const result = await client.finances.listFinancialEvents({
amazonOrderId: '333-7777777-7777777'
})
Options:
Name | Type | Default
-----|------|--------
maxResultsPerPage | Number
| 100
amazonOrderId | String
|
financialEventGroupId | String
|
postedAfter | Date
|
postedBefore | Date
|
nextToken | String
|
FulfillmentInboundShipment
Example:
const result = await client.fulfillmentInboundShipment.getBillOfLading({
shipmentId: 'FBAQFGQZ'
})
Options:
Name | Type | Default
-----|------|--------
shipmentId | String
|
Example:
const result = await client.fulfillmentInboundShipment.listInboundShipments({
lastUpdatedAfter: '2015-10-02T12:00:54Z',
lastUpdatedBefore: '2015-11-02T12:00:54Z',
shipmentStatusList: [
'WORKING',
'CLOSED'
],
shipmentIdList: [
'FBA44JV8R',
'FBA4X8YLS',
'FBA4X9FML'
]
})
Options:
Name | Type | Default
-----|------|--------
shipmentStatusList | Array<String>
|
shipmentIdList | Array<String>
|
lastUpdatedAfter | Date
|
lastUpdatedBefore | Date
|
nextToken | String
|
Example:
const result = await client.fulfillmentInboundShipment.listInboundShipmentItems({
shipmentId: 'SSF85DGIZZ3OF1'
})
Options:
Name | Type | Default
-----|------|--------
shipmentId | Array<String>
|
lastUpdatedAfter | Date
|
lastUpdatedBefore | Date
|
nextToken | String
|
FulfillmentInventory
Example:
const result = await client.fulfillmentInventory.listInventorySupply({
sellerSkus: [
'SampleSKU1',
'SampleSKU2'
],
responseGroup: 'Basic',
marketplaceId: 'ATVPDKIKX0DER'
})
Options:
Name | Type | Default
-----|------|--------
sellerSkus | Array<String>
|
queryStartDateTime | Date
|
responseGroup | String
|
marketplaceId | String
|
nextToken | String
|
Orders
Example:
const result = await client.orders.listOrders({
lastUpdatedAfter: '2017-02-01T18:12:21',
marketplaceId: [
'ATVPDKIKX0DER',
'A2Q3Y263D00KWC',
'A1VC38T7YXB528'
],
fulfillmentChannel: [
'MFN'
],
paymentMethod: [
'COD',
'Other'
],
orderStatus: [
'Unshipped',
'PendingAvailability'
]
})
Options:
Name | Type | Default
-----|------|--------
createdAfter | Date
|
createdBefore | Date
|
lastUpdatedAfter | Date
|
lastUpdatedBefore | Date
|
orderStatus | String
|
marketplaceId | Array<String>
| Selected region’s marketplaces
fulfillmentChannel | Array<String>
|
paymentMethod | Array<String>
|
buyerEmail | String
|
sellerOrderId | String
|
maxResultsPerPage | Number
| 100
easyShipShipmentStatus | Array<String>
|
nextToken | String
|
Example:
const result = await client.orders.getOrder({
amazonOrderId: [
'902-3159896-1390916'
]
})
Options:
Name | Type | Default
-----|------|--------
amazonOrderId | Array<String>
|
const result = await client.orders.listOrderItems({
amazonOrderId: '058-1233752-8214740'
})
Options:
Name | Type | Default
-----|------|--------
amazonOrderId | String
|
nextToken | String
|
Products
Example:
const result = await client.products.listMatchingProducts({
marketplaceId: 'ATVPDKIKX0DER',
query: '0439708184'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
query | String
|
queryContextId | String
|
Example:
const result = await client.products.getMatchingProduct({
marketplaceId: 'ATVPDKIKX0DER',
asinList: [
'B002KT3XRQ'
]
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
asinList | Array<String>
|
Example:
const result = await client.products.getMatchingProductForId({
marketplaceId: 'ATVPDKIKX0DER',
idType: 'ISBN',
idList: [
'9781933988665',
'0439708184'
]
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
idType | String
|
idList | Array<String>
|
Example:
const result = await client.products.getLowestPricedOffersForSku({
marketplaceId: 'ATVPDKIKX0DER',
sellerSku: '24478624',
itemCondition: 'New'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sellerSku | String
|
itemCondition | String
|
Example:
const result = await client.products.getLowestPricedOffersForAsin({
marketplaceId: 'ATVPDKIKX0DER',
asin: 'B00COK3FD8',
itemCondition: 'New'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
asin | String
|
itemCondition | String
|
Example:
const result = await client.products.getMyPriceForSku({
marketplaceId: 'ATVPDKIKX0DER',
sellerSkuList: [
'SKU2468'
]
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sellerSkuList | Array<String>
|
itemCondition | String
|
Example:
const result = await client.products.getMyPriceForAsin({
marketplaceId: 'ATVPDKIKX0DER',
asinList: [
'1933890517'
]
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
asinList | Array<String>
|
itemCondition | String
|
Example:
const result = await client.products.getProductCategoriesForSku({
marketplaceId: 'ATVPDKIKX0DER',
sellerSku: 'SKU2468'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sellerSku | String
|
Example:
const result = await client.products.getProductCategoriesForAsin({
marketplaceId: 'ATVPDKIKX0DER',
asin: 'B002KT3XQM'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
asin | String
|
Reports
Example:
const result = await client.reports.requestReport({
reportType: '_GET_FLAT_FILE_OPEN_LISTINGS_DATA_',
startDate: '2009-01-03T18:12:21',
endDate: '2008-06-26T18:12:21',
marketplaceIdList: [
'ATVPDKIKX0DER'
],
reportOptions: {
custom: true
}
})
Options:
Name | Type | Default
-----|------|--------
reportType | String
|
startDate | Date
|
endDate | Date
|
marketplaceIdList | Array<String>
|
reportOptions | String
or Object
|
Caveats:
When defining reportOptions
as an object, keep in mind that the options’ casing must match the MWS documentation.
Example:
const result = await client.reports.getReportRequestList({
reportRequestIdList: [
'2291326454'
],
reportTypeList: [
'_GET_ORDERS_DATA_',
'_GET_MERCHANT_LISTINGS_DATA_'
],
reportProcessingStatusList: [
'_DONE_'
]
})
Options:
Name | Type | Default
-----|------|--------
reportRequestIdList | Array<String>
|
reportTypeList | Array<String>
|
reportProcessingStatusList | Array<String>
|
maxCount | Number
| 100
requestedFromDate | Date
|
requestedToDate | Date
|
nextToken | String
|
Example:
const result = await client.reports.getReportList({
reportTypeList: [
'_GET_ORDERS_DATA_'
],
acknowledged: false,
reportRequestIdList: [
'2291326454',
'2294446454'
]
})
Options:
Name | Type | Default
-----|------|--------
maxCount | Number
| 100
reportTypeList | Array<String>
|
acknowledged | Boolean
reportRequestIdList | Array<String>
|
availableFromDate | Date
|
availableToDate | Date
|
nextToken | String
|
Example:
const result = await client.reports.getReport({
reportId: '624169093',
format: 'raw'
})
Options:
Name | Type | Default
-----|------|--------
reportId | String
|
format | Enum[raw, base64]
Sellers
Example:
const result = await client.sellers.listMarketplaceParticipations()
Options:
Name | Type | Default
-----|------|--------
nextToken | String
|
Subscriptions
Example:
const result = await client.subscriptions.registerDestination({
marketplaceId: 'AKIAEEXAMPLESA',
sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sqsQueueUrl | String
|
Example:
const result = await client.subscriptions.deregisterDestination({
marketplaceId: 'AKIAEEXAMPLESA',
sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sqsQueueUrl | String
|
Example:
const result = await client.subscriptions.sendTestNotificationToDestination({
marketplaceId: 'AKIAEEXAMPLESA',
sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sqsQueueUrl | String
|
Example:
const result = await client.subscriptions.createSubscription({
marketplaceId: 'AKIAEEXAMPLESA',
sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications',
isEnabled: true,
notificationType: 'AnyOfferChanged'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sqsQueueUrl | String
|
isEnabled | Boolean
| true
notificationType | String
|
Example:
const result = await client.subscriptions.deleteSubscription({
marketplaceId: 'AKIAEEXAMPLESA',
sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications',
notificationType: 'AnyOfferChanged'
})
Options:
Name | Type | Default
-----|------|--------
marketplaceId | String
|
sqsQueueUrl | String
|
notificationType | String
|
Example:
const result = await client.subscriptions.parseNotification(
`<Notification>
<NotificationMetaData>
<NotificationType>Test</NotificationType>
<PayloadVersion>1.0</PayloadVersion>
<UniqueId>0123456789-ca3b-4127-abe7-82cfbe19a032</UniqueId>
<PublishTime>2019-07-01T10:46:29Z</PublishTime>
<SellerId>XXXXXXXXXXTest</SellerId>
</NotificationMetaData>
<NotificationPayload>
<TestNotification />
</NotificationPayload>
</Notification>`
)
Options: Takes an XML string.
The following notifications are supported:
Test
AnyOfferChanged
FeedProcessingFinished
ReportProcessingFinished
Common
All entities except reports
support a getServiceStatus
method to retrieve the API status.
License
MIT
Miscellaneous
╚⊙ ⊙╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝