wmt-marketplace-sdk

Walmart Marketplace API SDK

Features

• Orders
  • All Release Orders: Retrieves all the orders with line items that are in the "created" status, that is, these orders have been released from the Walmart Order Management System to the seller for processing. The released orders are the orders that are ready for a seller to fulfill.
  • Acknowledge Orders: You can use this API to acknowledge an entire order, including all of its order lines. Walmart requires a seller to acknowledge orders within four hours of receipt of the order, except in extenuating circumstances.
  • Shipping Updates: Updates the status of order lines to "Shipped" and triggers the charge to the customer.
• Requests
  • Timeout: All requests are set with a 2-minute timeout to avoid overuse of resources when the API is slow to respond.

Roadmap

• Orders
  • We are working on completing the Orders methods.

Usage

You only need to set your API credentials once in the process. They don't need to be set for each call within the same process.

import { WMT } from 'wmt-marketplace-sdk';

WMT.Request.Credentials = new WMT.Config.Credentials(
  '38b7eb6c-3672-4022-93a2-f47794f36338', // Client ID
  'MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAUAwggE8AgEAAkEAq7BFUpkGp3...' // Client Secret
);

Get All Released Orders

WMT.Orders.getAllReleased({
  CreatedStartDate: new Date('01 April 2018 00:00 UTC'), // required
  CreatedEndDate: new Date('02 April 2018 00:00 UTC'), // optional, defaults to current time
  Limit: 10 // optional, defaults to 200 (max)
}).then((response: string) => {
  let purchaseOrders: WMT.Orders.PurchaseOrder.PurchaseOrderResponse = JSON.parse(response);

  // do something with the orders
});

Acknowledge Orders

WMT.Orders.ackOrder({
  PurchaseOrderId: 2380639477120
}).then((response: string) => {
  let orderResponse: WMT.Orders.PurchaseOrder.SingleOrderResponse = JSON.parse(response);
  // The response to a successful call contains the acknowledged order. Although the
  // API documentation claims the order will bear an "Acknowledged" status, we have
  // not found this to be true in production. It's simply a copy of the order that
  // was acknowledged, still bearing a "Created" status.
});

Shipping Updates

var shipment = new WMT.Orders.Shipment.OrderShipmentRequest(
  // See sample in /test/lib/orders.spec.ts ('Shipment Update').
);

WMT.Orders.postShippingUpdate({
  PurchaseOrderId: 2380639477120,
  PurchaseOrderShipment: shipment
}).then((response: string) => {
  let orderResponse: WMT.Orders.PurchaseOrder.SingleOrderResponse = JSON.parse(response)
  // The response to a successful call contains the purchase order.
});

Install

npm install --save wmt-marketplace-sdk

Scripts

• npm run build : rimraf ./lib/ && tsc -p .

Dependencies

Contributing

We are always excited when we can make our projects open source and allow contributors to build and work on these components. To make this possible, there are a few things we kindly ask all contributors to understand and follow. Please review the Contributing Guide.

Author

Kane McConnell kane@makanal.eu

License

• MIT : http://opensource.org/licenses/MIT

CHANGELOG

2023-07-14, Version 2.2.2, @kmcconnell

Notable Changes

• shipment:
  • Added currentTrackingInfo in shipment.ts.

2022-06-30, Version 2.2.1, @kmcconnell

Notable Changes

• shipment:
  • Fixed typo in shipFromCountry declaration.

2022-06-30, Version 2.2.0, @kmcconnell

Notable Changes

Eff. 2022-07-01, Walmart requires a ShipFromCountry for each line item submitted via Shipping Updates.

2019-08-26, Version 2.1.0, @kmcconnell

Notable Changes

Eff. 2019-08-28, Walmart is deprecating the signature based request and requiring an update to use the Token API instead. Requests have been updated to use the new authentication method.

2018-04-22, Version 1.3.4, @kmcconnell

Notable Changes

Walmart returns a 404 error when no results exist for API method. For example, if calling getAllReleased(), Walmart returns a 404 if no new released orders exist. However, when using this method with a time-based trigger, it's expected that some calls will return no results. Therefore, the 404 INFO response is now caught and returned as a Promise.resolve() rather than a thrown error.

[{"code":"CONTENT_NOT_FOUND.GMP_ORDER_API","description":"Failed when called getAllOrders. Orders not found for given search parameters"}]

• error:
  • Added WMTErrorResponse classes to help with handling Walmart errors. (Kane McConnell) #15
• request:
  • Improved ContentNotFoundError handler to separate info messages from actual error messages. (Kane McConnell) #15

2018-04-22, Version 1.3.3, @kmcconnell

Notable Changes

• request:
  • Added ContentNotFoundError filter to catch chain to handle parsing of Walmart error response when no results are returned for the requested parameters. The error description(s) are stringified as a JSON array and thrown as a new Error. (Kane McConnell) #15

2018-04-21, Version 1.3.2, @kmcconnell

Notable Changes

The return type of requests was updated to Request.Promise rather than PromiseLike. The PromiseLike type does not carry a catch() method, which meant parent modules could not chain catches onto the methods.

Now when using the Orders methods, developers can add custom .catch():

WMT.Orders.getAllReleased({
  // params
})
  .then((response: string) => {
    // do something with the response
  })
  .catch((error: Error) => {
    // handle the error.
  });

• request:
  • Changed return type of execute to Promise rather than PromiseLike, which did not have the .catch() method available when imported into parent modules. (Kane McConnell) #13
• orders:
  • Changed return type of all Orders methods to Request.Promise to pass through the .catch() method to parent modules. (Kane McConnell) #13

2018-04-17, Version 1.3.1, @kmcconnell

Notable Changes

• README:
  • Added documentation regarding the inaccuracies between Walmart Marketplace API documentation and production responses received. (Kane McConnell) #11
• request:
  • Added timeout of 120000 ms (2 minutes) to request promise to avoid overuse of resources when the API is down or slow to return response headers. (Kane McConnell) #11
• purchase:
  • Added SingleOrderResponse to WMT.Orders.PurchaseOrder to match object strutcture received when using the WMT.Orders.ackOrder() method. (Kane McConnell) #11

2018-04-17, Version 1.3.0, @kmcconnell

Notable Changes

• README:
  • Added example call for WMT.Orders.postShippingUpdate(). (Kane McConnell) #9
• orders:
  • Added postShipingUpdate() method to WMT.Orders module. (Kane McConnell) #9
  • Added Shipment to the WMT.Orders exports. (Kane McConnell) #9
• shipment:
  • Added Shipment classes. (Kane McConnell) #9
• purchase:
  • Changed the OrderLineTrackingInfo.trackingUrl property to optional. It is only required when CarrierName.otherCarrier is set. (Kane McConnell) #9
  • Changed the documentation for OrderLinePackageCarrier with more detail and acceptable carrier names. (Kane McConnell) #9
• request:
  • Added optional Body property to the request, used when the API expects a body in the request (i.e. shipping updates). (Kane McConnell) #9

2018-04-16, Version 1.2.0, @kmcconnell

Notable Changes

• README:
  • Added example call for WMT.Orders.ackOrder(). (Kane McConnell) #7
• orders:
  • Added ackOrder() method to WMT.Orders module. (Kane McConnell) #7
• request:
  • Changed Method in in the Request.RequestParams interface to an optional property to support calls that do not require query parameters. (Kane McConnell) #7
  • Added method property to the request promise. Previously, all calls were using the GET method. (Kane McConnell) #7
• package.json:
  • Changed versions of dependencies rather than relying on latest. (Kane McConnell) #7

2018-04-16, Version 1.1.0, @kmcconnell

Created new module, which includes the first Orders method: getAllReleased().