@bizon/mws-sdk v6.0.1

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:

Country specific MWS regions:

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:

Example:

const result = await client.finances.listFinancialEvents({
  amazonOrderId: '333-7777777-7777777'
})

Options:

FulfillmentInboundShipment

Example:

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

Options:

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:

Example:

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

Options:

FulfillmentInventory

Example:

const result = await client.fulfillmentInventory.listInventorySupply({
  sellerSkus: [
    'SampleSKU1',
    'SampleSKU2'
  ],
  responseGroup: 'Basic',
  marketplaceId: 'ATVPDKIKX0DER'
})

Options:

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:

Example:

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

Options:

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

Options:

Products

Example:

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

Options:

Example:

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

Options:

Example:

const result = await client.products.getMatchingProductForId({
  marketplaceId: 'ATVPDKIKX0DER',
  idType: 'ISBN',
  idList: [
    '9781933988665',
    '0439708184'
  ]
})

Options:

Example:

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

Options:

Example:

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

Options:

Example:

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

Options:

Example:

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

Options:

Example:

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

Options:

Example:

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

Options:

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:

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:

Example:

const result = await client.reports.getReportList({
  reportTypeList: [
    '_GET_ORDERS_DATA_'
  ],
  acknowledged: false,
  reportRequestIdList: [
    '2291326454',
    '2294446454'
  ]
})

Options:

Example:

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

Options:

Sellers

Example:

const result = await client.sellers.listMarketplaceParticipations()

Options:

Subscriptions

Example:

const result = await client.subscriptions.registerDestination({
  marketplaceId: 'AKIAEEXAMPLESA',
  sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})

Options:

Example:

const result = await client.subscriptions.deregisterDestination({
  marketplaceId: 'AKIAEEXAMPLESA',
  sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})

Options:

Example:

const result = await client.subscriptions.sendTestNotificationToDestination({
  marketplaceId: 'AKIAEEXAMPLESA',
  sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications'
})

Options:

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:

Example:

const result = await client.subscriptions.deleteSubscription({
  marketplaceId: 'AKIAEEXAMPLESA',
  sqsQueueUrl: 'https://sqs.us-east-1.amazonaws.com/51471EXAMPLE/mws_notifications',
  notificationType: 'AnyOfferChanged'
})

Options:

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

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