@bizon/mws-sdk

    5.2.1 • Public • Published

    mws-sdk

    SDK for Amazon Marketplace Web Services

    npm version codecov XO code style

    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

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

    Install

    npm i @bizon/mws-sdk

    DownloadsWeekly Downloads

    81

    Version

    5.2.1

    License

    MIT

    Unpacked Size

    176 kB

    Total Files

    200

    Last publish

    Collaborators

    • tusbar