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

listFinancialEventGroups

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`

listFinancialEvents

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

getBillOfLading

Example:

const result = await client.fulfillmentInboundShipment.getBillOfLading({
  shipmentId: 'FBAQFGQZ'
})

Options:

Name	Type	Default
shipmentId	`String`

listInboundShipments

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`

listInboundShipmentItems

Example:

const result = await client.fulfillmentInboundShipment.listInboundShipmentItems({
  shipmentId: 'SSF85DGIZZ3OF1'
})

Options:

Name	Type	Default
shipmentId	`Array<String>`
lastUpdatedAfter	`Date`
lastUpdatedBefore	`Date`
nextToken	`String`

FulfillmentInventory

listInventorySupply

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

listOrders

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`

getOrder

Example:

const result = await client.orders.getOrder({
  amazonOrderId: [
    '902-3159896-1390916'
  ]
})

Options:

Name	Type	Default
amazonOrderId	`Array<String>`

listOrderItems

const result = await client.orders.listOrderItems({
  amazonOrderId: '058-1233752-8214740'
})

Options:

Name	Type	Default
amazonOrderId	`String`
nextToken	`String`

Products

listMatchingProducts

Example:

const result = await client.products.listMatchingProducts({
  marketplaceId: 'ATVPDKIKX0DER',
  query: '0439708184'
})

Options:

Name	Type	Default
marketplaceId	`String`
query	`String`
queryContextId	`String`

getMatchingProduct

Example:

const result = await client.products.getMatchingProduct({
  marketplaceId: 'ATVPDKIKX0DER',
  asinList: [
    'B002KT3XRQ'
  ]
})

Options:

Name	Type	Default
marketplaceId	`String`
asinList	`Array<String>`

getMatchingProductForId

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

getLowestPricedOffersForSku

Example:

const result = await client.products.getLowestPricedOffersForSku({
  marketplaceId: 'ATVPDKIKX0DER',
  sellerSku: '24478624',
  itemCondition: 'New'
})

Options:

Name	Type	Default
marketplaceId	`String`
sellerSku	`String`
itemCondition	`String`

getLowestPricedOffersForAsin

Example:

const result = await client.products.getLowestPricedOffersForAsin({
  marketplaceId: 'ATVPDKIKX0DER',
  asin: 'B00COK3FD8',
  itemCondition: 'New'
})

Options:

Name	Type	Default
marketplaceId	`String`
asin	`String`
itemCondition	`String`

getMyPriceForSku

Example:

const result = await client.products.getMyPriceForSku({
  marketplaceId: 'ATVPDKIKX0DER',
  sellerSkuList: [
    'SKU2468'
  ]
})

Options:

Name	Type	Default
marketplaceId	`String`
sellerSkuList	`Array<String>`
itemCondition	`String`

getMyPriceForAsin

Example:

const result = await client.products.getMyPriceForAsin({
  marketplaceId: 'ATVPDKIKX0DER',
  asinList: [
    '1933890517'
  ]
})

Options:

Name	Type	Default
marketplaceId	`String`
asinList	`Array<String>`
itemCondition	`String`

getProductCategoriesForSku

Example:

const result = await client.products.getProductCategoriesForSku({
  marketplaceId: 'ATVPDKIKX0DER',
  sellerSku: 'SKU2468'
})

Options:

Name	Type	Default
marketplaceId	`String`
sellerSku	`String`

getProductCategoriesForAsin

Example:

const result = await client.products.getProductCategoriesForAsin({
  marketplaceId: 'ATVPDKIKX0DER',
  asin: 'B002KT3XQM'
})

Options:

Name	Type	Default
marketplaceId	`String`
asin	`String`

Reports

requestReport

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.

getReportRequestList

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`

getReportList

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`

getReport

Example:

const result = await client.reports.getReport({
  reportId: '624169093',
  format: 'raw'
})

Options:

Name	Type	Default
reportId	`String`
format	`Enum[raw, base64]`

Sellers

listMarketplaceParticipations

Example:

const result = await client.sellers.listMarketplaceParticipations()

Options:

Name	Type	Default
nextToken	`String`

Subscriptions

registerDestination

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`

deregisterDestination

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`

sendTestNotificationToDestination

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`

createSubscription

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`

deleteSubscription

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`

parseNotification

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

    ╚⊙ ⊙╝
  ╚═(███)═╝
 ╚═(███)═╝
╚═(███)═╝
 ╚═(███)═╝
  ╚═(███)═╝
   ╚═(███)═╝

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

bizon / mws-sdk

Programming Languages

Labels

Projects that are alternatives of or similar to mws-sdk

mws-sdk

CI

Getting started

Usage

Region and Marketplaces

Pagination

Error handling

API

Finances

FulfillmentInboundShipment

FulfillmentInventory

Orders

Products

Reports

Sellers

Subscriptions

Common

License

Miscellaneous