Walmart Open

Walmart Open is Walmart's official products search and ordering API. There are actually two distinct API endpoints: one for product search and lookup and one for ordering.

Products API

To use the Products API, you must register for a Walmart Open account and obtain an API key. You can also API calls from their interacive API tool. For documentation can be found here: https://developer.walmartlabs.com/docs.

Commerce API

As of right now, the Commerce API is only available to select partners. Once you've established a relationship with them, you will need the following to access the Commerce API:

API Key
API Secret
Generated Private/Public Key for message signing. You will need to give them your public key before proceeding.
A billing record id; Provided to you by Walmart when you give them your public key.
A walmart.com account that is connected to your Walmart Open account.

Installation

Add this line to your application's Gemfile:

gem 'walmart_open'

And then execute:

$ bundle

Or install it yourself as:

$ gem install walmart_open

Usage

Configuring the Client

require "walmart_open"

client = WalmartOpen::Client.new do |config|
  ## Product API
  config.product_api_key = "GggS6aPxDteRCyRxYnqz9bPp"

  # This value defaults to 5.
  config.product_calls_per_second = 4

  ## Commerce API
  config.commerce_api_key = "7XQLSmhqTXJHQ5xdGG7ZUh8d"
  config.commerce_api_secret = "Mm5BX4c7QC"
  config.commerce_private_key = File.read("/path/to/your/private/key/file")

  # This value defaults to 2.
  config.commerce_calls_per_second = 1

  # Set this to true for development mode.
  # This mainly applies to the Commerce API; orders will not actually be placed.
  config.debug = true
end

Making Product API Calls

# Search
res = client.search("ipod")
#=> SearchResults
# example of res
# res.query = "ipod"
# res.total = 53259
# res.start = 1
# res.page = ?
# res.items = [ Item_1, Item_2 ....]

# Lookup (by item id)
item = client.lookup(15076191)
#=> item is of class WalmartOpen::Item, see WalmartOpen::Item section for detail
# When item not found, an error of class WalmartOpen::ItemNotFoundError is thrown,
  eg: {"errors"=>[{"code"=>4002, "message"=>"Invalid itemId"}]}
  When walmart api is down, an error of class WalmartOpen::ServerError is thrown,
  eg: {"errors"=>[{"code"=>504, "message"=>"Gateway Timeout"}]}

# Taxonomy
taxonomies = client.taxonomy
#=> Array
# when success, example of one of taxonomies
# taxonomies.categories = {"id"=>"5438", "name"=>"Apparel", "path"=>"Apparel", "children"=>[{"id"=>"5438_426265",
  "name"=>"Accessories", "path"=>"Apparel/Accessories", "children"=>[{"id"=>"5438_426265_1043621",
  "name"=>"Bandanas", "path"=>"Apparel/Accessories/Bandanas"}, ...]]}

# Search special feeds (by feed type, category id)
# Feed type can be :preorder, :bestsellers, :rollback, :clearance, :specialbuy
# For :preorder case, you do not need to pass param category_id
items = client.feed(:bestsellers, category_id)
#=> Array
# when success: items is an array of WalmartOpen::Item items

Making Commerce API Calls

# Placing an Order
order = WalmartOpen::Order.new(billing_id: 1, partner_order_id: "38",
                               partner_order_time: "16:15:47",
                               first_name: "James", last_name: "Fong",
                               street1: "200 Blossom Ln",
                               street2: "100 Flynn Avenue",
                               city: "Mountain View",
                               state: "CA", zipcode: "94043", country: "USA")
# required fields:
# billing_id: long, first_name: string, street1: string, city: string,
  state: string, zipcode: string, country: string, phone: string
# optional fields:
# last_name: string
# partner_order_time: string in format of HH:MM:SS, default to Time.now
# partner_order_id: string, default to "Order-#{HASH_OF_RAND_AND_ORDER_TIME}"

# add_item method 1, add_item(item_id, quantity = 1, item_price = nil, shipping_price = nil )
order.add_item(10371356)
order.add_item(25174174)

# add_item method 2, add_item(item, quantity = 1)
order.add_item(client.lookup(10371356))
order.add_item(client.lookup(25174174))

# order.valid? == true

res = client.order(order)
#=> OrderResults
# when order succeeds, we see res as example below
# res.error? = true
# res.order_id = "2677911409503"
# res.partner_order_id = "13"
# res.items = [ ordered_item, ...]
# res.total =  "237.96"  # sum of ordered_item.price for all ordered_items
# res.sales_tax = "20.82"
# res.surcharge = "0.0"
# res.raw_attributes = {"response"=>{"orderId"=>"2677914395453", "partnerOrderId"=>"41", "items"=>{"item"=>{"itemId"=>"10371356", "quantity"=>"1", "itemPrice"=>"22.97"}}, "total"=>"29.95", "itemTotal"=>"22.97", "shipping"=>"4.97", "salesTax"=>"2.01", "surcharge"=>"0.00"}}

# Note that order_item have class OrderedItem. As an example
# ordered_item.id = 25174174
# ordered_item.quantity = 1
# ordered_item.price = 214.99
# ordered_item.raw_attributes = {"itemId"=>"25174174", "quantity"=>"1", "itemPrice"=>"214.99"}

# when order fails, we see res as below
# res.error? == true
# res.error = {:code=>"10001", :message=>"Invalid xml"}
# res.error[:code] = "10001"
# res.error[:message] = "Invalid xml"
# res.raw_attributes = {"errors"=>{"error"=>{"code"=>"10001", "message"=>"Invalid xml"}}}

WalmartOpen::Item

example of a WalmartOpen::Item item

item.id = "15076191"

item.name = "Apple iPod Touch 4th Generation 32GB with Bonus Accessory Kit"

item.price = "189.0"

item.upc = nil

item.category_node = "3944_96469_164001"

item.short_description = "The world's most popular portable gaming device ... "

item.long_description = "<br><b>Apple iPod touch 32GB (4th Gen) ..."

item.brand = nil

item.shipping_rate = 0.0

item.size = nil

item.color = "Black"

item.model_number = ?

item.url = "http://www.walmart.com/ip/Apple-iPod-Touch-8GB-32GB-and-64GB-newest-model/15076191"

item.raw_attributes = => 15076191, .....

item.large_image = "http://i.walmartimages.com/i/p/00/80/14/18/71/0080141871195_Color_Burgundy_SW_500X500.jpg"

item.thumbnail_image = "http://i.walmartimages.com/i/p/00/80/14/18/71/0080141871195_Color_Burgundy_SW_100X100.jpg"

item.medium_image = "http://i.walmartimages.com/i/p/00/80/14/18/71/0080141871195_Color_Burgundy_SW_180X180.jpg"

item.variants returns an array of product ids when a walmart product has

variants that user can choose, eg a different color or style. An example:

items.variants = [15076191, 15076192]

An empty array is returned when a product has no variants.

Authentication failure

In the case of authentication failure during an API call, a WalmartOpen::AuthenticationError exception will be raised

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request