Skip to content
This repository has been archived by the owner on Feb 6, 2023. It is now read-only.
/ mws-sdk Public archive

JavaScript SDK for Amazon Marketplace Web Services (MWS)

License

Notifications You must be signed in to change notification settings

bizon/mws-sdk

Repository files navigation

mws-sdk

SDK for Amazon Marketplace Web Services

npm version codecov XO code style

🚀 Switching to the Selling Partner API? See our modularized SDK library for Amazon Selling Partner API (fully typed in TypeScript).

Bizon

CI

Tests Release

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

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