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.
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.
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.
Add this line to your application's Gemfile:
gem 'walmart_open'
And then execute:
$ bundle
Or install it yourself as:
$ gem install walmart_open
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# 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# 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 = {"itemId" => 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.available? returns true when an item is available online
# item.stock.available? returns true when item stock is "Available"
# item.stock.not_available? returns true when item item stock is "Not available"
# item.stock.few? returns true when item item stock is "Last few items"
# item.stock.limited? returns true when item item stock is "Limited Supply"
# 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.In the case of authentication failure during an API call, a WalmartOpen::AuthenticationError exception will be raised
- 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